DataMasque Portal

API Reference Overview

Documentation Overview

This API Reference documentation page provides details on how to use the DataMasque API. If you're new to working with REST APIs, please read the Quickstart Examples section, which provide an overview of using Postman and curl. Otherwise, check the API Endpoints documentation to quickly access information about each endpoint and their curl examples.

Quickstart Examples

The examples on this page use < and > as delimiters for example values, but these characters should not be used in the requests.

Preface

These examples are made for beginners new to using REST APIs. We'll guide you step by step on how to use Postman and curl to interact with the DataMasque API. Remember, the type of request (GET, POST, PUT, etc.) depends on what is specified in our documentation for each endpoint.

An Overview of Making Requests With Postman

Please note that this documentation is based on Postman version 10.22. Future or previous versions of Postman may have slightly different options or behaviors.

Aside from the Postman example listed in the Authentication section, this is the only Postman example. However, a curl example will be listed for each endpoint.

  1. Open Postman: Launch the Postman application on your device.

  2. Create a New Request:

    • At the top of your window, select the File menu tab, then select New.
    • At modal will appear which will ask what type of request is needed. Select HTTP.

  3. Set the Request Method:

    • Above the URL field, you'll see a dropdown menu. This is where you specify the type of request (GET, POST, PUT, etc.) as indicated in our documentation for the endpoint you are using.

  4. Enter the URL:

    • In the URL field, type https://<your-datamasque-host>/<your-desired-endpoint>/.
    • Replace <your-datamasque-host> and <your-desired-endpoint> with the appropriate values provided in our documentation.

  5. Set Headers (For POST / PUT Requests):

    • If the request type is POST or PUT, you'll need to set some additional headers.
    • Go to the Headers tab just below the URL field.
    • Add two keys: Content-Type and Accept. For both, set the value to application/json, unless specified as a different value in that endpoint's documentation.

  6. Add Request Body (For POST/PUT Requests):
    Sometimes a request body needs to be specified for sending special types of request parameters to the DataMasque API. One example of is this is during the API Token retrieval request. When making PUT or POST requests, check the endpoint's documentation listed on this page to see if a request body is needed.

    • Switch to the Body tab.
    • Select raw and choose JSON from the dropdown menu that appears.
    • Enter the JSON-formatted data as specified in our documentation.

  7. Authorization (If Required):

    • Some requests might require an authorization token.
    • In the Headers tab, add a new key Authorization.
    • Set its value to Token <your-api-token>, replacing <your-api-token> with your actual token.

  8. Send the Request:

    • Click the Send button to dispatch your request.

  9. Check the Response

    • Under the Response section which takes up half of the My Workspace window in Postman, take a look at the returned response body under the Body tab.
    • If the response body is empty, take a look at the Status header to the right of the response section.
    • There should be a numerical code e.g. 200 followed by some text. If the text is not OK and the status code is 400 is higher, check the Body tab's returned JSON object to see if any error details have been specified.
    • If there are no error details returned in the response body, check if the status code next to the Status header is one listed in the Common Failure Responses of our API documentation. This details provided there should give more insight into what may have caused the error.
    • If the status code is not listed there, refer to the endpoint's section of this documentation for any endpoint-specific error codes and their details.

An Overview of Making Requests With curl

Please note that this documentation is based on curl version 8.50.0. Future or previous versions of curl may have slightly different options or behaviors.

  1. Open Your Command Line Interface:

    • Access your terminal on macOS or Linux, or your command prompt or PowerShell on Windows.

  2. Construct Your Request:

    • Start by typing curl. This is the basic command to use the curl tool.
    • Specify the request method by adding -X request followed by the method (POST, PUT, etc.) as indicated in our documentation for the endpoint you are using. (If the request method is GET, you do not need to include the -X GET flag as that is the default.)

  3. Enter the URL:

    • After -X <METHOD>, type the full URL of the API endpoint you wish to call.

  4. Set Headers:

    • For sending headers with your request, use the -H flag followed by the header in quotes.
    • For most requests, especially POST or PUT, set the Content-Type and Accept headers to application/json, unless specified as a different value in that endpoint's documentation.

  5. Add Request Body (For POST/PUT Requests):

    • When the request type is POST or PUT, and you need to send data, use the -d option followed by the data in JSON format.
    • Ensure you've checked the endpoint's documentation to verify if a request body is needed.

  6. Include Authorization Token (If Required):

    • If an endpoint requires an authorization token, add it to the headers using the -H flag.
    • For example, -H "Authorization: Token <your-api-token>", replacing <your-api-token> with the actual token you received from the token retrieval endpoint.

  7. Send the Request:

    • After constructing the full curl command with all the necessary flags and data, press Enter to send the request.

  8. Check the Response:

    • The response will be printed directly in the terminal. Review the response body and headers to ensure your request was successful.

Quickstart generic example with curl

curl -X <GET | POST | PUT |  DELETE> "https://<your-datamasque-host>/<your-desired-endpoint>/" \
     -H "Authorization: Token <your-api-token>" \
     -H "<your-additional-headers>"

Common Responses

Upon making a request, as part of the HTTP response, you will receive a status code and potentially some details about the success status of the request made.

Most successful request response status codes will be in the range 200 to 299. For each endpoint detailed in this documentation, their expected success status codes and descriptions are listed.

However, when a response is not successful, there are several common failure response status codes which are useful to be aware of.

There may be several status codes which deviate from the ones mentioned in the following section, however, these will be listed in this documentation under specific endpoint sections.

Common Failure Responses

Status Code Description
400 Bad Request: Check the JSON body and response for more information.
401 Unauthorized: Token required.
403 Forbidden: User is not allowed.
404 Not Found.