FAQ

I want to test an API in the developer portal. What should I do?

See section How to get access to the APIs above.

Which user should I use to create a subscription with?

Scenario 1 - Personal testing: If you have a BOS user, login and create subscription as described in the How to get access to the APIs section. If you don't have a BOS user you can send an email/Service Now case to the integration team requesting a subscription.

Scenario 2 - System usage: When the subscription is going to be used by a system it should be registered by the xxxxx with a BOS user described in the How to get access to the APIs section. If xxxxx does not have a BOS user an email/Service Now case can be sent to the integration team requesting a subscription.

Can I have multiple subscriptions for the same API

Yes, this is important to distinguish between personal and system subscriptions. You can have one subscription for personal testing and another subscription on behalf of a system. 

I want to use an API in a system. What should I do?

You need a separate subscription for the system to ensure. Create a subscription similar to a personal subscription, but the subscription name shall start with System_<Name of the system>. After approval, navigate to the "My subscription" and get the subscription key required to invoke the API. 

What is the Ocp-Apim-Subscription-Key?

This is a header which must be included in the request in order to authenticate. It can be gotten when a subscription has been activated. To see it you can navigate

Do I need to have one Ocp-Apim-Subscription-Key for each APIM environment?

Yes, you need to create a separate subscription in the different APIM environments in order to get access to the different environments.

Do I need to have one subscription for each API for a system? Can I have one subscription covering multiple API's for simplicity?

For personal testing you need to have one subscription for each API's. If your system needs to invoke several API and you have good reasons to have one subscription, contact the BOS central API team to create a subscription. 

I want to test APIs with other tools like Postman. What should I do?

TBD

How does pagination work with the APIs exposed with the APIM portal?

In general, the endpoints that support pagination of some sort will use a continuation token which is included in the response (header) and must be included in the request header to get the next page. A query parameter will also be available to set the maximum number of items returned. That said, there might be different implementations regarding pagination dependent on the underlying backend system, meaning the documentation for each API endpoint must be read before using them. Users can expect one API to only use one type of pagination setup.

I want to expose one of my APIs. How do I proceed?

Create a Service Now case with the Integration Team as the assigned group with information about what you want to expose. When the case is being worked on every information you will need will be provided related to access to Azure resources, how to deploy to the APIM instance, standards, how to document the API, and so on.

I am interested in the versioning of the APIs exposed in this APIM. How is versioning implemented?

The version is only included in the URL and does only consider major versions. https://api.bos.no/customer-api/v2/customers is the URL to version 2 of the customer API and the collection of customers that the API provides. When minor changes are done to the API, e.i. NONE-BREAKING changes, the version does not need to updated.

How can I specify trace/correlation context?

The APIs exposed in this API Management portal uses the W3C Trace Context. This means that in order to add an existing trace/correlation id the format for the traceparent header must be used. It should be noted that the APIs will not give you an error when the header is not on the correct format, they will instead use the traceparent header as parent id and generate a new trace id. With other words if the specified format is not followed the global correlation id will be changed. If no traceparent header is included in the request Azure will provide one. All APIs will give a response header (traceresponse) where the trace/correlation id will be presented on the format stated in the documentation above.

Request header format (traceparent)

The format of the traceresponse header is divided into four parts: version, trace-id, parent-id, trace-flags
Version and trace-flags should both be set to 00.

format = version "-" trace-id "-" parent-id "-" trace-flags
version = 2HEXDIGLC ; 8 bit flags.
trace-id = 32HEXDIGLC ; 16 bytes array identifier. All zeroes forbidden
parent-id = 16HEXDIGLC ; 8 bytes array identifier. All zeroes forbidden
trace-flags = 2HEXDIGLC ; 8 bit flags.

Response header format (traceresponse)

The response header is similar to the request header, except that the parent-id is replaced with the child-id or the span-id of the server handling the client request.Heading 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.