Consume your first API
This tutorial is for application developers who need to call an API another team has published. At the end you have an application with credentials, subscribed to an API, and you know where to find the specification and your usage.
Before you begin, you need:
- An API-dex account. Any signed-in user can create applications.
- The name of the API you want to call, or a good idea of what it does.
Subscribe and call
Sign in and select the environment
Sign in with your organisation account. Open the environment control in the top bar and select the environment the API is published to, for example your test gateway.
Find the API
Open APIs from the main navigation. Browse or search the catalog and select Documentation on the API's card. Its page shows the available versions and the interactive specification.
Read the specification
Check the operations, parameters and schemas you need. If several versions exist, open the page menu beside the title and use Compare versions to see what changed between them.
Create an application
Open My Applications from the main navigation, then select New application. Enter the Application name, pick the API you found in step 2 under Select APIs, leave Credentials generation on Automatic and Submit. An application is your client registration: it holds the credentials and the list of APIs it may call.
Check the subscription
Open the application. The APIs table lists the API with its status. Where the organisation requires approval for new subscriptions, the status stays pending until an administrator approves it; it then reads Approved. To add more APIs later, select + above the table (Add/Remove APIs), or Request access on any API card.
Copy the credentials
The Credentials card shows the key, secret or token in the format the gateway expects, masked. Select the eye button to reveal a value and the copy button that appears beside it. Paste it into your service's secure configuration and treat it like a password.
Make the call
Call the API endpoint from the specification, sending the credential as the specification describes. The call goes to the gateway directly. API-dex is not in the request path.
INFO
The first time you create an application, API-dex offers a guided tour that walks through these steps in the interface, including an example request.
What's next
- Managing your applications: rename, share with your team, add more APIs or delete an application.
- Viewing your analytics: see traffic per application once calls are flowing.
- Managing your teams: share the application with a consumer team so colleagues use the same registration.