# API Design Principles
source: https://developer.mastercard.com/mdes-pre-digitization/documentation/api-basics/design_principles/index.md

The MDES Pre-Digitization API is designed as a set of RPC-style, stateless web services where each API endpoint represents an operation to be performed. All request and response payloads are sent in the JSON (JavaScript Object Notation) data-interchange format. Each endpoint in the API specifies the HTTP Method used to access it. All strings in request and response objects are UTF-8 encoded. Each API URI includes the major and minor version of API that it conforms to. This allows multiple concurrent versions of the API to be deployed simultaneously.

All APIs return an HTTP response code of 200 if the call was successfully received and accepted for processing. To ensure forward-compatibility, all API integrations must be resilient to new elements being added to requests. Any errors that subsequently occur during processing are returned in the response payload.

### URL Scheme {#url-scheme}

All API URLs follow the format: **scheme://host\[ :port \]/contextRoot/api/majorVer/minorVer/apiName**

example: <https://www.issuersite.com/tokenizationMTF/issuerServices/1/0/authorizeService>

|   URL Element   |                                                                      Definition                                                                      |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| scheme          | https                                                                                                                                                |
| host\[ :port \] | Hostname (and port number if required) for the environment. e.g. [www.issuersite.com](https://www.issuersite.com)                                    |
| contextRoot     | Context root for the services. e.g. /tokenizationMTF                                                                                                 |
| api             | issuerServices                                                                                                                                       |
| majorVer        | The major version of the API. This is not related to the version of this document. This version of the document corresponds to a major version of: 1 |
| minorVer        | The minor version of the API. This version of the document corresponds to a minor version of: 0                                                      |
| apiName         | The URL endpoint as defined in the respective section for the API operation. e.g. authorizeService                                                   |

Note: The issuer can define Hostname and contextRoot as per thier system. The issuer must use the api, majorVer, minorVer value as defined above and apiName is the endpoint as defined [API Reference](https://developer.mastercard.com/mdes-pre-digitization/documentation/api-reference/index.md).

### Retry Strategy {#retry-strategy}

MDES will automatically retry 3 times with up to a 5-second wait between each attempt of the DeliverActivationCode, NotifyServiceActivated, and NotifyTokenUpdated API calls that fail with a:  

* Timeout
* Connection failure
* HTTP response code of 302, 500 or 503

If the call does not succeed after the initial retries, MDES will attempt a second round of 3 retries with increasing time intervals between each retry. Between attempts the system will wait 15 minutes, 30 minutes, and then 2 hours. In case of a 503 response code, the Retry-After header will be respected, if present, and will count as a retry.