# API Design Principles
source: https://developer.mastercard.com/account-to-account-commerce-for-dsp/documentation/api-basics/api-design-principles/index.md

## Design Principles {#design-principles}

The following design principles apply for Account to Account Commerce:

* Mastercard Account to Account Commerce APIs are designed as RESTful APIs.
* All request and response payloads are exchanged in JSON (JavaScript Object Notation) data-interchange format.
* The string fields are to be sent as UTF-8 encoded.
* The date fields are to be sent in UTC (Coordinated Universal Time) with time and a special UTC designator ("Z")" wherever applicable.
* The customer must handle any standard HTTP response codes that could result from an API call including, but not limited to, 200, 400, 401 and 500.
* Any errors that occur during request processing are returned in the response payload.

## Readiness for versionless API changes {#readiness-for-versionless-api-changesbr}

As part of the API's versionless strategy, all API participants should expect future releases of the API to evolve and introduce non-breaking changes.   

Ensuring that API participants are resilient to non-breaking changes requires careful attention to schema validation and marshalling implementations.  

Non-breaking changes are typically additive, which is to say that they represent changes like the addition of content to an API payload, the inclusion of a new endpoint URL or the addition of another HTTP verb. API services can be conservative in what is sent, but API clients must be liberal in what is accepted.  

As non-breaking changes modify existing API endpoints, participants must ensure the following:  

* API client code must be resilient to all types of non-breaking changes.   
* API client code must ignore any aspects of the message that are not part of the original documentation, provided that they fall within the remit of a non-breaking change.   
* Schema validation and marshalling must be resilient to adding non-breaking changes in response payloads. For example, new fields may be added to responses in future releases.  
* When the Account to Account Commerce is making outbound API calls to services hosted by participants, the request payloads may also be subject to non-breaking changes, such as the addition of new fields.   

## Idempotency {#idempotency}

Account to Account Commerce APIs support idempotency for POST operations through the idempotency-key header. When an API client experiences timeouts due to temporary network glitches or doesn't receive a response from the server, the client may retry sending the same request with the same idempotency-key value. Other operations, that are idempotent in nature, e.g., PUT, don't use the idempotency-key header for supporting this behaviour. This behaviour is applicable to selected POST operations that may result into duplicates, e.g., duplicate payments. API specs document the idempotency-key header, where this function is supported.   

For endpoints supporting idempotency, the API client must send an idempotency key header populated with a unique value along with the request. The API client must send the same value in subsequent retries of the same request to avoid duplicate processing. API client may choose to cache/persist this value in order to achieve this. When the API service receives a request containing an idempotency-key with a value seen previously within the idempotency window, it will send the same response back instead of reprocessing the request. In the retried request, the API client must include the unique value of X-Request-ID for traceability and troubleshooting. Where digital signing is applicable, those requests and responses are expected to be signed again. When a request with a previous idempotency-key is retried beyond the idempotency window, the request can be processed as a new request, which results in a new transaction.  

Where the idempotency-key header is included in outbound APIs, idempotent behaviour must be implemented by participants for services hosted by participants. Account to Account Commerce may retry requests in case of timeouts received from services hosted by participants. Participants may choose to implement such behaviour based on a unique resource id, e.g., an agreement-id, where only one message is expected for that resource id.  

Idempotency window- The window of idempotency behaviour is currently set to 2 minutes; however, it is configurable and may be updated in the future.