Understanding API requests
A REST request to Informer is built from a handful of parts. Knowing what each one does makes the API Reference much easier to read.
Method
The method says what you want to do with a resource:
- GET: ask for a resource or list (for example, retrieve a list of Datasets).
- POST: create or append (for example, append data to a Dataset). Repeating a POST is usually not safe.
- PUT: replace a resource or trigger an action with the data you supply (for example, replace a Dataset's data). Repeating a PUT is safe.
- DELETE: remove a resource (for example, delete a Dataset).
- PATCH: change part of a resource. Less common than the others.
Host
The host (or base URL) is the start of the full URL, like https://informer.company.com. It depends on your Informer instance and tenant, so most examples leave it out to stay instance-agnostic.
Route
The route (or URI) identifies the resource and is the part of the URL after the host. Routes are the same across instances, so examples include the full route. Most start with /api/, and some contain a variable to replace, such as {datasetId}.
Headers
Headers are key/value pairs carrying information about the request. The most common is authentication, the token or credentials that prove who is asking.
Parameters
Parameters are key/value pairs that refine which resource, or which part of it, you want, such as filtering data or asking for a specific page of results.
Informer's REST docs avoid the word "query" for these to prevent confusion with Informer Queries.
Payload
The payload (or body) is data you send to the server, available only on POST, PUT, and PATCH requests and usually describing the change to make. Payloads to Informer's API are typically JSON.