Interrogation data formatted in the M5 File format can be submitted from M5, I5 or by using the PTAGIS web API. The API includes two endpoints (load and remove) for submitting M5 files in a RESTful manner.
To submit files using the PTAGIS API, data contributors will need to do the following:
1.Obtain an API key from PTAGIS.
2.Build a properly formatted M5 file.
3.Use the /submissions/interrogation/authorize endpoint to request authorization to submit a file.
4.Use the JSON web token (JWT) returned from the call in #3 with the appropriate /submissions/interrogation endpoint to either load or remove the file (see sample code).
5.Use the /submissions/interrogation/{id} endpoint with the Submission ID to request the status of the file after it has processed.
If you plan to build an application to submit M5 files using the web API, you should use the Test API (https://testapi.ptagis.org) while developing and testing the application. Files submitted using the Test API will be processed using the test system and will not be loaded into the production database.
The /submissions/interrogation/authorize call requires the following parameters:
•API Key: a GUID assigned to you (contact PTAGIS to receive one)
•Site Code: the interrogation site for which data will be submitted
•Registered Email Address: an email address registered with PTAGIS as allowed to submit data for that site
Sample Code
The following C# sample code shows how to include the JWT returned from the authorize code in the subsequent call to actually submit the data.
private static async Task SubmitDataToPtagis(InterrogationFile file, string authToken)
{
var console = new ConsoleEx(true); try
{
var baseUri = @"https://api.ptagis.org";
var requestUri = @"interrogation/submission/load";
var client = new HttpClient();
client.BaseAddress = new Uri(baseUri);
client.DefaultRequestHeaders.Add("token", authToken);//JWT from auth process
var response = await client.PostAsJsonAsync(requestUri, file);
if(response.IsSuccessStatusCode) //HTTP call failed
{
var submission = await response.Content.ReadAsAsync<SubmissionModel>();
if (submission.Status == SubmissionStatusType.Failed)
{
console.WriteLine($"PTAGIS could not process {file.FileName}: ");
foreach (var err in submission.Errors)
console.WriteLine(err);
}
else
console.WriteLine($"PTAGIS accepted
{file.FileName} with status of
{submission.Status}.");
}
else
console.WriteLine($"HTTP failure: ({response.StatusCode}) {response.ReasonPhrase} ");
}
catch (Exception ex)
{
console.WriteLine($"Error submitting {file.FileName}: {ex.Message}");
}
}
File Load Status Response
Interrogation files that do not meet format specifications will generate a Bad Request (400) response when submitted via the web API with content such as:
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-53c04c6850137344bbc33307a7857618-559a719db20ca44c-00",
"errors": {
"SystemDescription": [ "The SystemDescription field is required." ],
"InterrogationFieldData[1537].FieldData":
[ "The field FieldData must be a string or array type with a maximum length of '500'." ]
}
}
After the file is accepted for processing, the submissions/interrogation/{id} endpoint can be used to request the status of the file. Possible responses are shown below:
|
Response |
Definition |
|
Pending |
File has not been processed. |
|
Rejected |
The file did not pass data validation requirements and was not loaded. More information can be found in the Message element of the response. |
|
Failed |
An unanticipated error occurred during file processing. Please contact PTAGIS for more information. |
|
Loaded |
First successful load of a data file with this name. |
|
Stored |
File was stored in the PTAGIS file archive, but not loaded into the database. This reserved for secondary and test submission files. |
|
Removed |
File and all data contained in it has been successfully removed. |
Version: 1.07
Published: 9/6/2023