Hi!
Here we’ll explain briefly how to onboarding API’s to Veracity API Management (APIM).
First: Why use APIM?
APIM functions as a proxy between your API backend and your customer. This means that you only have to allow calls from APIM (IP address 13.69.21.200 ), and you can block all other requests by IP. This greatly increases the security of your backend. APIM has built-in security features like a simple authorization scheme, as well as DDOS protection.
Through APIM you can take a single a API and re-package it as several products. Say you have a single API - through APIM you can create a bronze, silver and gold package where each level has a different amount of API calls included (either total amount of calls or per time unit, like calls/month). Veracity APIM will handle restrictions and block clients that have gone above the allotted amount of calls.
Next: How do I onboard my API to APIM?
Send us the OpenAPI definition file!
You’ll need to comply with a few requirements though:
- OAS 3.0 / Swagger 2.0 compliant.
- The “servers” element must be present with your root URL defined.
- Run it through a Swagger validator to ensure it doesn’t have any errors.
The image above shows a snip from https://editor.swagger.io for a compliant example API. Look for the green symbol to know your API is compliant.
You’ll also have to decide if you want versioning or not. If you go with versioning, we recommend the “path” type versioning to make it easier for your customers to use the API.
Inform us about your versioning choice when sending us the API definition file.
You will also need to think about your authorization model.
Contact us to discuss authorization methods if you have not picked one already.
Finally: How does the end user interact with my API through APIM?
This depends on how you have planned the authorization model in your API backend.
But generally the end user will get a subscription key and a token which they will need to send as headers when making API calls.
The subscription key will be visible in the Veracity for Developers portal when you log in (https://developer.veracity.com/)
The swagger documentation for your APIM-endpoints will be visible for the end user on the API Explorer (https://developer.veracity.com/docs/section/api-explorer/api-explorer) . The end user can make calls to APIM to test your API.
The end user would need to input subscription key, token, and whatever engineering parameters are required for your API to respond (e.g. steel thickness or IMO number for a ship).
The subscription key is used to make a call to a Veracity APIM endpoint for your API.
The key is a default header for all calls. APIM will pass on API calls from anyone with a valid subscription key for your API. APIM will not check the token content which is sent, it will only control that it is there.
What type of token the user should send as a header depends on the authorization model. As the API owner you are in control of who you let in, and who should be blocked.
For example if you choose to use Veracity user tokens for authorization, it is possible for your backend to check the user’s Veracity service subscriptions and determine access/no access based on that. Note that a Veracity service subscription and APIM subscription key are two different things.
Checking a user’s service subscriptions can be done by making an API call towards a specific Veracity endpoint, however this will require that your backend is integrated with Veracity Identity. Contact us to learn more.
Common methods for identifying the user:
For API’s sold over the Veracity Marketplace we can create static long-lived tokens for the customer. This token will then contain information about the customer.
OR
We use Veracity user tokens obtained through authorization code flow.
OR
We use a non-personal Veracity token obtained through client credentials flow, which usually represents an application instead of a user. This is relevant in cases where server-to-server calls are necessary and you cannot rely on a Veracity user token being present.
Contact: onboarding@veracity.com
Changelog:
2023-01-16:
Added Veracity APIM IP address.
2024-06-18:
Removed mention of the API Portal and replaced it with the API Explorer and Veracity for Developers.