API Requests
Endpoint URLs
The format of the API URL is very simple: https://api.geoop.com/:collection[/:item][/:action]
| Variable | Format | Example | Required | Description |
|---|---|---|---|---|
:collection |
[A-z]+ |
jobs |
Yes | Collection name. |
:item |
[0-9]+ |
157 |
No | Identifier of an entity within the collection. |
:action |
[A-z]+ |
upload |
No | Name of an action to be applied to a collection or an item (if specified). |
Examples
Get the list of all jobs of a subscriber: GET https://api.geoop.com/jobs
Change information about user with ID 1234: PATCH https://api.geoop.com/users/1234
Upload a binary file: POST https://api.geoop.com/files/upload
Versioning
Since the request and response formats may change from one version of the API to another, you must specify the required version of the API in the X-Version header. If the specified version is invalid or outdated, then an error response will be returned.
The API will report its version in the X-Version response header.
Request Methods
| Method | Description | Restrictions |
|---|---|---|
GET |
Retrieve a list of items in a collection or an item with the specified ID within that collection. | This method is not allowed for actions. |
POST |
Create one or more items within the specified collection. Apply an action to the specified collection or item within that collection. |
This method is allowed only for collections and actions. |
PATCH |
Update one or more items within the specified collection. | This method is not allowed for actions. |
DELETE |
Delete one or more items within the specified collection. | This method is not allowed for actions. |
The request method verb can be specified in a special X-Method header. This is a way to make correct requests for solutions that support only limited number of verbs (and do not allow making requests such as PATCH).
Note that the value specified in the header overwrites the actual type of the request. For example, a PATCH request with the X-Method header having the GET value will be interpreted by the API as a GET request.
Also note that it is not always possible to set the request body for the GET request. Therefore, when it is required to simulate PATCH and DELETE requests, it is recommended to use POST request with a custom X-Method header. Simply put, use GET for reading and POST for writing.