Developer Guidelines

Overview

This section will provide information regarding naming standards, URL structure, best practices, security guidelines, validation and so on.

Each API configured in APIM should have a display name and description. Using easy to understand descriptions and metadata greatly assist identification for management and usage.

Consider using display name and description fields on APIs to convey intended purpose and usage. Display name and description fields should be human readable and easy to understand.

Restriction

Some restriction which should be considered while naming different resources in APIM are available here.

URL Structure

Here is the recommendation for the API URL

https://<Host Name>/<department>/<information_object>/v1/

Department : Distinguish APIs by areas
Information_object : Customers, Computers etc (optional)
V1 : version

Example: https://api.sandvik.com/group/getusers/v1/ or https://api.sandvik.com/secotools/getproducts/v1/

Use of hyphens(-)
Use the hyphen (-) character to better readability of long names path segments in URL.

Tagging

Naming Convention

API Name

API name should be unique be it at the root level or workspace level.

Name: <System/Department/Business Area> <Information Object/Operational Purpose>

Example: ServiceNow CI Stream
Example: SMSConnect Recycling Collection
Example: SecoTools Product Visualization

API name should not include consuming system name.

Named Value Pair

It should be unique be it at root level or under workspace.

Name: <Department/BA Name>-<Named Value Pair>
Example: SMSConnect-SIIPClientId
Note: In case of naming apiJwtAudience the naming standard should like apiJwtAudience-smsconnect

Products

API Management products should have a display name and description.

Each product created in API Management can have a display name and description set. Using easy to understand descriptions and metadata greatly assist identification for management and usage.

Consider using display name and description fields on products to convey intended purpose and usage. Display name and description fields should be human readable and easy to understand.

During monitoring from service provider perspective:

• Having a clear understanding of the purpose of a product is often important to during analysis.

• Allows for accurate management and clean up of unused or old products.

• Allows for accurate access control decisions.

This information is visible within the developer portal.

It should be unique be it at global level or under workspace.

Name: <SystemName/Department/Business Area> or <SystemName><API Collection Name>
Example: DigitalIdentity or NetIQ Computers
Example: SMSConnect SECO API or SMSConnect Recycling Collection

When creating the product, following checks should be in place.

Requires subscription
Requires approval

Subscription

Subscription Name is unique hence we should follow the below naming standard.

Product Subscription Naming: "ISVCXXXX-" + Subscriber Name

Example:

• ISVC0047-ServiceNow

• ISVC0049-MyWizard

API Operations

Name: <Purpose>
Example: Create Incident

If you have the backend system API documentation available then kindly match the operation names with the backend API documentation.

Workspace

Name: <BA/Division/TeamName>
Example: SMSConnect or SecoTools or DigitalIdentity

Versioning

API Versioning in API Manager allows the new version of the same API to be published seamlessly without breaking the existing service that is actively being consumed by the API Consumers. This also allows the API Consumers to smoothly transition of the newer version.

Versioning can be handled using Path, Header or Query String and it is the Path based approach that is widely and recommended in this naming convention. It is shorter and more readable.

Policies

Following policies should be incorporated for each of the API.

Tracing

Tracing the Integration agreement for each API request

Add the following policy either at all operations or policy per operation based on the scenario

<trace source="APITag" severity="information">ISVCXXXX <API Name></trace>

Subscription Key

Removal of the subscription key from each request

<set-header id="apim-generated-policy" name="Ocp-Apim-Subscription-Key" exists-action="delete" />

JWT Token Validation

Validation of JWT Token with claims

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
<openid-config url="https://login.microsoftonline.com/sandvik.onmicrosoft.com/.well-known/openid-configuration" />
  <audiences>
   <audience>{{App Registration ID}}</audience>
  </audiences>
 <required-claims>
  <claim name="appid" match="any">
   <value>{{mywizard_appid}}</value>
  </claim>
 </required-claims>
</validate-jwt>

Kindly declare the policies as global policies where ever possible. For example, removing the header subscription key from all incoming request can be added as a global policy for your API operations.

Diagnostics Settings

• Select APIs from the menu on the left.

• Click on the API.

• Go to the Settings tab from the top bar.

• Scroll down to the Diagnostics Logs section.

• On the Application Insights tab check the Enable box.

• In the Destination dropdown select the logger you just added in the Application Insights blade.

• Set sampling to 100 to capture all events.

• Check the Always log errors checkbox.

App Registration

In order to facilitate authentication and authorization applications need to be registered. TO request a new app registration you need to create a request on Service Portal.

App Registration

New Naming Standard: GITINT.<Env>.SystemName/Department/ApplicationName

Example: GITINT.Dev.ServiceNow

Env: Dev / QA / Prod

APIM Product, Groups and Subscription Strategy