This guide will walk you through the steps needed to interact with our API, particularly for fetching a specific resource, in this case Enterprise Report. The API is documented using Swagger, which provides a clear and interactive documentation of all the available endpoints, their expected input, and output formats. To access Enterprise Report, you will need to follow a three-step process:
Issue an Authentication Token
Fetch the proper Business Unit
Request for Enterprise Report
Below are the detailed instructions for each step, assuming you are starting with no prior setup.
Step 1: Issue an Authentication Token
Before you can make any requests to our protected endpoints, you need to authenticate using your credentials to obtain a token.
a. Navigate to the Swagger Documentation
Access the Swagger API documentation page by visiting the X-Analytics API site.
b. Issue a Token
In the Swagger UI, locate the authentication endpoint. It's under Auth category, labeled as Issue access token
Click on the endpoint to expand the details.
Click the "Try it out" button, which enables you to make a test request directly from the Swagger page.
Enter your credentials in the required fields.
Submit the request by clicking the "Execute" button.
c. Retrieve Your Token
After submitting your credentials, the response body will be displayed within the Swagger UI.
Look for the access token in the response.
Copy the token value; you will need this for subsequent requests.
Step 2: Fetch the Proper Business Unit
With the token, you can now fetch the list of business units and select the correct one for accessing Enterprise Report.
a. Authorize Your Session
Find the authorization button in the Swagger UI, which might be a lock icon or a button labeled "Authorize"
Click on it and enter your token.
Once you Authorize, click "Close" to exit the authorization box.
This will append the token to the headers of your subsequent requests.
b. Fetch the List of Business Units
Locate the endpoint responsible for listing business units. It's under Business Units category, labeled as List business units.
Expand the endpoint details and click "Try it out."
Execute the request.
c. Select the Correct Business Unit
From the list of business units returned, identify the business unit you need. There is identifying information such as a id.
Note the identifier of the correct business unit.
Step 3: Request for Enterprise Report
Now that you have the right business unit ID and a valid token, you can proceed to request Enterprise Report.
a. Locate the Enterprise Report Endpoint
In the Swagger UI, find the endpoint that allows you to fetch Enterprise Report. It's under Enterprise category, labeled as Get latest report.
Expand the details of the endpoint.
b. Make the Request
Click on "Try it out."
Enter any required parameters, including the business unit ID you obtained earlier.
Ensure your authentication token is still active; if not, re-authorize as described in Step 2a.
Submit the request by clicking the "Execute."
c. Access Enterprise Report
After executing the request, you should receive a response that includes the details of Enteprise Report.
If the request was successful, the response code should be 200 (OK), and the response body will contain the data for Enteprise Report.
If there are any errors (e.g., a 401 Unauthorized), ensure your token is valid, and you've input the correct business unit ID.
Notes and Troubleshooting
Tokens are typically short-lived. In our case it's 30 minutes. If you encounter authentication issues, repeat Step 1 to issue a new token.
Always ensure that you are using https for making requests to keep your credentials secure.
Refer to the status codes and responses in the Swagger documentation to troubleshoot any issues you encounter.
If you have any difficulties or questions, contact the support team for assistance.
Remember, the Swagger UI is an interactive tool. It's not only for reading documentation but also for making live API calls, which can greatly aid in understanding the API's behavior and debugging issues.
コメント