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.