Idempotency
An API is considered idempotent when repeated identical requests yield the same outcome without causing any errors. This indicates that calling the API multiple times has the same effect as calling it just once.
All GET
, PUT
, and DELETE
requests to Spotnana APIs are idempotent by default.
However, certain POST
requests that create a resource on the server side will not exhibit the same behavior.
For example, the Create company API
is not idempotent.
Handling Non-Idempotent POST APIs
POST
APIs used for resource creation are not idempotent (e.g., Create company API).
To address scenarios where a client may accidentally call such POST
APIs several consecutive times, these APIs can
contain an externalId
as part of the request. In case of network errors, you can still retrieve the resource identifier using this externalId
(provided if the resource creation was successful).
To explain this scenario with an example, consider the Create company API.
When you're calling this API to create a new company, you can include an optional externalId
in the request to specify an external identifier.
The first API call will create a new resource. However, since the Create company API
is not idempotent, you may encounter an error if you run this API with consecutive identical requests.
In such cases, to fetch the newly created resource information, you can use the externalId
on the
List companies API.
The following code snippet is a sample curl
request of the List companies API
where the externalId
is added as a query parameter.
curl -i -X GET \
'https://apis.spotnana.com/v2/companies?externalId=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Note: Most APIs have a unique identifier (e.g., a unique company name) which prevents the creation of duplicate resources. The
externalId
is an additional measure to make sure the API client doesn't create a duplicate record on the server.