41 lines
2.6 KiB
Markdown
41 lines
2.6 KiB
Markdown
The AgMission API is a set of HTTP endpoints that help your app integrate with AgMission. Check out the HTTP documentation below to learn about everything you can do with the API.
|
|
|
|
The AgMission API allows clients to communicate with AgMission Server, including functionality like checking for Job assigment, downloading, uploading job items and/or data.
|
|
|
|
To test the API, developers can use some tools such as [PostMan](https://www.getpostman.com/), [CURL](https://curl.haxx.se/), etc.
|
|
|
|
### **Request and response formats**
|
|
In general, the AgMission API uses HTTP POST requests with JSON arguments and JSON responses. Request authorization uses JWT token in the Authorization request header.
|
|
|
|
Common API responses includings: standard HTTP error code and JSON content within the HTTP response body. Depending on the status code, the response body may be in JSON or plaintext. Sucessful responses always contain `200` status code.
|
|
|
|
### **Authentication and Authorization**
|
|
|
|
Before a client can call any api function, it needs to passthrough authentication (login) step, only require once until the token expired. After login, the authentication server return to the client an authorization token. Then, for subsequent api calls, clients must include the token to each request's Authorization header.
|
|
|
|
For example: a POST request with `"Authorization:Bearer mytoken123"` header using CURL
|
|
~~~
|
|
curl -X POST http://<host>:<port>/api/exports/anyJob \
|
|
--header "Authorization: Bearer mytoken123"
|
|
~~~
|
|
|
|
Agmission REST API uses [JWT](https://jwt.io/), JSON Web Token, to authorize client requests.
|
|
|
|
### Errors
|
|
Like sucessful responses, error ones are also returned using standard HTTP error code syntax. For response codes with JSON Content-Type, look in the JSON error.tag value for the specific error.
|
|
|
|
| Code | Description |
|
|
| ----------- | ----------- |
|
|
| 401 | Bad or expired token. It can happen if the access token is expired or has been revoked by AgMision. To continue using the API, client need to re-authenticate (login step) using the provided user account. The Content-Type of the response is JSON.
|
|
| 409 | Endpoint-related error. Normally, it refers to user input specific errors. The Content-Type of the response is JSON. |
|
|
| 5xx | An error happended on the AgMission servers. Contact with AgMission administrator for details.|
|
|
|
|
### Date format
|
|
All dates in the API use UTC and are strings in the ISO 8601 ["combined date and time representation"](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format:
|
|
|
|
2018-05-15T25:00:38Z
|
|
|
|
### Case insensitivity
|
|
The API is case-insensitive, meaning that `/A/B/methoda` is the same file as `/a/b/methodA`.
|
|
|