Overview

This article walks you through:

  • The components and overviews of REST API request/response pair.

  • The registration of token for authentication to secure REST requests.

  • The list of HTTP response status codes.

REST API Request/Response

Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the service’s resources. Components of a REST API request/response:

  1. The request URI, which consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Although the request URI is included in the request message header, it will be called out separately here because most languages or frameworks require you to pass it separately from the request message.

    • URI scheme: Indicates the protocol used to transmit the request. For example, http or https. Use https and SSL when calling all methods.

    • URI host: Specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as http://gdex.azure-api.net.

    • Query string (optional): Provides additional simple parameters, such as the filter or resource selection criteria.

  2. HTTP request message header fields:

    • A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Azure REST APIs support GET, HEAD, PUT, POST, and PATCH methods.

    • Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request.

  3. Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters. For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as application/json.

  4. HTTP response message header fields:

    • A HTTP response status code, ranging from 2xx success codes to 4xx or 5xx error codes. Alternatively, a service-defined status code may be returned, as indicated in the API documentation.

    • Optional additional header fields, as required to support the request’s response, such as a Content-type response header.

  5. Optional HTTP response message body fields. MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a JSON format, as indicated by the Content-type response header. For example, when you request an API endpoint, it is returned in the response body as the data element. In this example, a response header of Content-Type: application/json is also included.

Authentication

Almost every API has a method in place to authenticate requests. To make a web API call from a client, you must supply an access token on the call. The token acts like an electronic key that lets you access the API. Thus, myGDEX uses token for authenticating the API calls. Two types of token are used to authenticate an API calls as follows:

  • Subscription Key - Developer Access Token

    1. Go to myGDEX Open API Developer Platform, log in into your developer account.

    2. Go to myGDEX Subscription page, subscribe and obtain your Developer Access token.

  • User Token - User Access Token
    For myGDEX (Cash Customer Portal)

    1. Go to myGDEX Portal, log in into your user account.

    2. Go to User Profile page, generate and obtain your User Access token.

    For myGDEX Prime (Account Customer Portal)

    1. Go to myGDEX Prime Portal, log in into your user account.

    2. Go to API Token page, generate and obtain your User Access token.

HTTP Response Status Code

REST messages sent to myGDEX API instance return a specific HTTP response status code. The standard HTTP response status codes used are:

  1. 200 OK - The response code in this range implies the API call has succeeded.

  2. 400 Bad Request(Client Error) - The response codes indicates failure due to wrong input (i.e, client) side. A JSON with warning details should be returned to the client.

  3. 401 Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.

  4. 404 Not Found - The requested resource could not be found.

  5. 500 Internal Server Error - The response code indicates API request was valid but failed due to bugs on myGDEX server side. A JSON with an error should be returned to the client.