API Quickstart

In this section, you'll find a step-by-step guide to quickly start using the API.

Prerequisites

Before you start, make sure you have the following:

An account on our platform (Please reach your Disney representative to get the account)
Basic knowledge of HTTP and RESTful APIs

Authentication

Our API uses OAuth 2.0 for authentication. This means you'll need to obtain an access token to authenticate your requests. Here's how you can do this:

Register your application with our platform to obtain your client credentials (client ID and client secret).
Send a POST request to our authentication endpoint with your client credentials to obtain an access token. The request should look something like this:

POST /v2/as/token.oauth2 HTTP/1.1
Host: cp-auth-service.maestro.dmed.technology
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials&scope=RETURN_ALL_CLIENT_SCOPES

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual client ID and client secret. The server will respond with an access token. The response will look something like this:

Sample CURL Request:

curl --location 'https://cp-auth-service.maestro.dmed.technology/v2/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<REAPLCE_WITH_YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<REAPLCE_WITH_YOUR_CLIENT_SECRET> \
--data-urlencode 'scope=RETURN_ALL_CLIENT_SCOPES' \
--data-urlencode 'grant_type=client_credentials'

Response:

{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600
}

Include this access token in the Authorization header of your API requests. The header should look something like this:

Authorization: Bearer YOUR_ACCESS_TOKEN

Remember to securely store your client credentials and access token, and never share them publicly.

Making Your First Request

Once you have your access token, you can make your first request to our API. Let's start with a simple GET request to the /orders endpoint, which retrieves information about orders.

Here's an example of how to make this request:

GET /orders HTTP/1.1
Host: dotapi.ordering.dmd.disney.com
Authorization: Bearer YOUR_ACCESS_TOKEN

Replace YOUR_ACCESS_TOKEN with the actual access token you received.

The server will respond with a JSON object containing the orders' information. Here's an example of a typical response:

{
  "content": [
    {
      "orderId": "string",
      "orderName": "string",
      "orderType": "string",
      "status": "string",
      "orderSubmittedDate": "string"
    }
  ]
}

Response Handling

When you make a request to the API, the response will contain a status code, headers, and a body. Here's how to interpret these components:

Status Codes

The status code indicates the result of the request. Common status codes include:

200 OK: The request was successful.
401 Unauthorized: Authentication failed or was not provided.
403 Forbidden: Authentication succeeded, but the authenticated user does not have access to the requested resource.
500 Internal Server Error: An error occurred on the server.

Response Body

The response body contains the data returned by the API in response to your request. This data is typically in JSON format. Here's an example of how to parse this data in JavaScript:

const response = // the API response
const data = JSON.parse(response.body);

Error Handling If the API returns an error, the response will include an error message and an error code. Here's an example of an error response:

{
  "status": 401,
  "error": "Unauthorized"
}

When you receive an error response, check the error code to determine the cause of the error. In this case, the status code is 401 (Unauthorized), and the error message is "Unauthorized". You should get the new access_token.

API Usage Tips

Here are some tips to help you use our API effectively:

Use the correct HTTP methods: Each endpoint in our API is designed to respond to a specific HTTP method. Make sure you're using the correct method (GET, POST, PUT, DELETE, etc.) for each request.
Handle pagination: If an endpoint returns a large amount of data, the response may be paginated. Check the response headers or body for pagination links or tokens.
Rate limiting: Be aware of the rate limiting policies of our API. If you make too many requests in a short period of time, your requests may be throttled.
Error handling: Always check the HTTP status code and error messages returned by the API. This will help you understand what went wrong when a request fails.
Use filters and query parameters: Many endpoints support filters and query parameters that can help you narrow down the data you're retrieving.
Keep your access tokens secure: Your access tokens are like passwords. Keep them secure and don't share them.
Use the correct content type: When sending data to the API, make sure you're setting the Content-Type header correctly and that the body of your request matches that content type.
Stay updated: We regularly update our API with new features and improvements. Check our API documentation regularly to stay updated.

Next Steps

Now that you've made your first request to our API and learned how to handle the responses, you're ready to explore further. Here are some next steps you might consider:

Explore More Endpoints: Our API has many more endpoints that you can use to interact with our platform. Check out our API Reference for a complete list of endpoints and their functionalities.
Integrate the API into Your Application: Start integrating our API into your application. Use the access token to authenticate your requests and use the endpoints to perform actions.
Learn About Advanced Features: Our API has several advanced features, such as filtering and sorting data, batch requests, and webhooks. You can learn more about these features in our API Documentation.
Handle Errors and Edge Cases: Learn how to handle different types of errors and edge cases in your application. This includes invalid requests, server errors, and rate limiting.
Optimize Your API Usage: Learn how to optimize your API usage to ensure your application runs smoothly. This includes using pagination to handle large amounts of data, caching data to reduce server load, and using webhooks to receive real-time updates.

Remember, the key to effectively using an API is understanding how it works and how to handle different scenarios. Don't hesitate to experiment and learn as you go.

09 July 2024