1.1. Introduction¶

To succeed in the modern digital world, and to serve customers with on-demand, real-time information and services, companies the world over have been building or employing platforms that enable them to unlock the business values of their back-end data and services. The technology that is enabling this digital transformation is Application Programming Interfaces (APIs). APIs empower businesses to unlock the full potential of their informational assets and propel them further to the growth path. Through their open interfaces, APIs provide businesses with the perfect channel to more effectively engage with their customers and partners, which puts them at a competitive advantage over their competitors. Companies using APIs have increasingly been able to connect better with their consumers, thereby setting a solid foundation for future expansions of their businesses.

Why API Management?

APIs allow an enterprise to explore a new distribution channel, and profit from a fresh revenue stream, turning a part of its digital assets, data and services into valuable products. To capitalize on the full business potential of APIs, an enterprise needs strategies that lay down a strong foundation for managing APIs. By having a proper API platform in place, you can ensure that designing, deploying and managing an API becomes easier, as well as safe, secure and functional.

An API management platform is equipped with pre-built set of tools and functionalities that can simplify the process of designing, publishing, safeguarding and monitoring APIs. Using a management platform, an enterprise can centrally manage and monitor APIs, while ensuring that the developers connect securely to add business value through their rich applications.

What is DigitMarket™ API Manager?

DigitMarket™ API Manager also known as DM APIM is an API Management solution that enables enterprises to leverage existing back-end applications and usher in new businesses via cloud and mobile API channels.

1.1.1. DigitMarket™ API Manager Features¶

The three main components of DigitMarket™ API Manager are:

Publisher Portal
Developer Portal
Gateway

1.1.1.1. Publisher Portal Features¶

Advanced API Management

Create Secure API Proxies
Create API Packs from multiple APIs
Create transformation rules using JavaScript
Import and Generate Swagger 2.0 specification
REST to/from SOAP Conversion with Native REST support

Monetization

Attach pricing plans
Define free and paid quotas
Optionally collect Setup and termination fees
Generate rate card for the store

Policy Enforcement

OAuth 2.0
Request Throttling
Request Rate Limiting
Time of the day limiting
XML and JSON threats protection
Back-end overload protection
Cluster-wide global policies

Multiple Publisher Teams

Built in Multi-tenancy to allow each Business Unit to expose their own APIs
Each tenant can customise the developer portal
Optionally collect Setup and termination fees
Optional publisher driven developer on-boarding

Granular Control

Fine-grained control on publisher functions for users and groups
Delegated administration

Workflows

Approval cycles for common API publishing tasks
Separation of concerns for Business and Technical users
Approval of pricing definition and changes
Approval of policies
Optional Approval of Developer registrations

Identity Management Integration

Integration points to easily plug your own identity management
Map your enterprise directory to publisher users and groups

Billing Integration

Integration points to easily plug your own billing system
Extensibility of built-in Monetization rules

Customization

Every function in Publisher and Developer portal is an API. Customise as you wish.

Analytics

Built-in Analytics for Publishers to track API use
Dashboards and charts within publisher portal
Leverage data for custom reporting

Developer Portal Content Management

Customization at each tenant level
No third-party content management dependency. Plain and Simple HTML files.
Every developer portal feature is an API. Integrate your own content management or website.

1.1.1.2. Developer Portal Features¶

Self Service

Developer self-registration
Delegated administration
Application Registration

Subscription Management

API Plan Subscription request
Subscription renewal

Workflows

Approvals for production use

Key Management

Self-service based Token generation
API-driven token life cycle management
Subscription key management

Integrated Discussion Forum

Two-way Publisher-Consumer communication forum
Feature request submission
Bug tracking

Analytics

Integrated Analytics to track API usage
Revenue share reporting

1.1.1.3. Gateway Features¶

Event driven HTTP request processing
High concurrency
JavaScript engine for high-speed header and payload transformation
OAuth 2.0
HTTP Basic
API-driven and Publisher portal-driven administration
Asynchronous statistics and log recording
XML and JSON threat protection
Rate limiting and throttling policy enforcement
Back-end Protection
WS security
Maximum Concurrent Transactions
Data recording and masking

1.1.2. Architectural Overview¶

Fig. 1.1 DigitMarket™ API Manager Architecture

1.1.3. Key Concepts¶

If you are new to the world of APIs, this section will help you understand the concepts and terms that you are likely to encounter in your work as an API Publisher/Consumer. Below each of these key API terminologies is touched upon briefly.

1.1.3.1. Publisher Portal¶

The Publisher portal is a web portal for publishing, promoting and monitoring Application Programming Interfaces (APIs) in a secure and scalable platform.

Publisher portal provides the necessary tools to:

Define, design and publish APIs
Manage versions and life cycles of all artifacts related to API Management
Create, publish and promote APIs among the developer community
Help enforce runtime policies
Analyze API usage and make use of statistical information
Customise and brand the Developer Portal and drive API consumption

1.1.3.2. API¶

An API is a set of resources or operations that a Developer application can interface and invoke. The resources or operations expose web services via endpoints and make it possible for an application to consume them. Application Developers access data exposed over the Web via APIs and reuse the already available logic from the data in their applications.

API publishers expose a back-end application by implementing it as a proxy in the API Gateway. A proxy acts as a go-between for developers of consuming applications and API publishers. To manage exposed APIs, publishers define policies that specify standards the applications have to comply with.

Companies all over the world are creating APIs from various sources to make their applications work. One such point in reference is that of Uber, which, apparently found success by leveraging several APIs, such as Google Maps for its location mapping, Twilio for SMS alerts, SendGrid for emails, and Braintree for payments. By doing this, it has been able to avoid heavy costs of engineering a product from the scratch.

Fig. 1.2 API

There are two major types of Web APIs:

SOAP APIs
REST APIs

SOAP API

SOAP is a protocol with standard specifications to define messages, bindings, operations, and location of a web service. It is used to expose each operation, having application logic, as a web service. Being function-driven, SOAP performs operations. Take for instance: changeEmployeeName(EmployeeID, oldEmployeeName, newEmployeeName), which is an operation that fetches the Employee ID and uses the parameters oldEmployeeName and newEmployeeName to change the employee name.

SOAP APIs have stateful implementation, which means that a session’s state is used to service subsequent sessions. SOAP permits only XML as the data format and makes use of WSDL (more on WSDL later in this section) schemas to define the XML structure and every operation used in an API. It allows formal contracts to define the interface that the Web Service offers.

SOAP APIs are a practical choice in cases where it is important to have high reliability in transactions and a need for formal contracts between APIs and its consumers, for instance, banking applications.

WSDL

You use WSDL to define web services and describe how consumers can access these services. WSDL describes the technical specifications of a web service; like what a web service does, how it communicates and where it lives in the server.

The WSDL must use well-formed XML format with basic WSDL syntax. It must identify the services provided by the server and specify the set of operations within each service.

You can associate an XSD file with the WSDL to check if the XML is properly structured and if it is a valid WSDL document. An XSD defines a schema for the XML document, ensuring that the XML structure is as laid out by the schema. Associated XSD is embedded inline with the WSDL document or imported as a separate file along with the WSDL file.

DigitMarket™ API Manager enables its users to create a SOAP web service from a WSDL file. To create a SOAP web service, you must first create and import a WSDL file or a Zip file that has a WSDL and a XSD file in it. Content of the file is then parsed and the required data extracted and populated to the API Operations definition.

REST API

REST is an architectural style unlike SOAP, which is a protocol. A REST API is specified as a URI and works over standard HTTP. The requested resource is accessed through standard CRUD methods (GET, PUT, DELETE, and POST). HTTP being a stateless protocol does not allow the state of the service to persist beyond one request and response. REST permits many data formats including JSON, XML, YAML or any other machine-readable format.

REST is data-driven. In the SOAP example above, if you were to use REST, you would define a URI, like so: http://sample.test/api/employee/22. A PUT action (with the new Employee name passed in the body) to the URI would accomplish the update of the old employee name. A GET action to the URI confirms the change with the HTTP status code 200.

REST’s advantages include ease of integration and development as it is based on HTTP and makes use of CRUD operations. It is a good choice for mobile applications and web-based projects as it does not require heavy protocols. The statelessness of REST is designed to ensure scalable solutions that support many users.

1.1.3.3. What is a Proxy Endpoint and Real Endpoint¶

Endpoints are server-side connection points or URLs using which a web service can be accessed by client-side devices. They are entities used by a web service to connect, typically using an HTTP URL string in the form of say, http://myapi.com/someservice/. A web service can have multiple endpoints exposed for consumption. Endpoints have specific URL addresses to which a web service message can be sent and from where a response can be received. In short, an endpoint is a point of reference that generates and terminates information. You can have any number of endpoints pointing to a Resource/Operation. For example, in a REST URI http://apis.com/mobiles, we can have multiple endpoints that refer a particular mobile ID, such as http://apis.com/mobiles/1234, or http://apis/mobiles/1235, etc.

Real Endpoint

A Real Endpoint is the target endpoint that forwards request calls to the back-end services. The end-users and Developer users do not have the knowledge of the Real Endpoints as their applications interface with the exposed Proxy Endpoints to make their requests.

In DigitMarket™ API Manager, a Real Endpoint is represented in the following form: http://<IP or hostname>:<port>/<path>.

Proxy Endpoint

A Proxy Endpoint dissociates the back-end system from the exposed Real Endpoint; exposing only those parts of the back-end application that is required by an API. You can configure a Proxy Endpoint by specifying a URL. Clients indirectly reference the back-end services using the proxy endpoint. Security policies, usage limits and access control are attached to the Proxy Endpoint.

Fig. 1.3 Proxy and Real Endpoints

1.1.3.4. API Pack¶

API Packs are how APIs are presented to developers. An API Pack is a packaged collection of resources/operations formed from various APIs and contains allowed methods. Once they are ready for consumption, Packs are made available in the API Store in the Developer portal. Developers can explore different Packs in the Store and subscribe to a Pack Plan(s) to use the APIs.

Fig. 1.4 Proxy and Real Endpoints

1.1.3.5. API Monetization - Usage Plans¶

A Usage Plan is a configuration that the customer can buy through subscription. It specifies the pricing configurations, including free and paid-tier pricing, and if paid, the monthly fees and sign-up fees that are applicable. Usage Plans are created using API resources/operations present in a Pack, which are secured and bound by security Policies and Usage Policies.

Monetization Strategies

There are the following Monetization Strategies:

Usage-based Pricing - This Monetization Strategy defines pricing based on the number of API calls made over a fixed period. This strategy type can have multiple Usage Plans.
Revenue Sharing-based Pricing - This Monetization Strategy defines Pricing based on the revenue that an API generates and as is generally stated in predefined agreements, a portion of the revenue is shared with the Developer. This strategy type can have only one Usage Plan.
Transaction-based Pricing - This Monetization Strategy ties pricing to transaction value, which is a percentage of the transaction value. A Publisher user can configure the percentage. Transaction-based Pricing applies to each individual transaction made through an API. This strategy type can have only one Usage Plan.
Non-Monetized - Non-monetized strategy does not have a subscription fee or a One-time fee. The Publisher user can choose to limit the subscription term validity under a Usage Plan to a specific number of months or have a Usage Plan active for an unlimited period. The user can also choose to service an unlimited number of requests under a Plan. This strategy type can have several usage plans.

A Pack can only accept a single Monetization Strategy for all its Plans. All Usage Plans that you add to a Pack are going to have the same Monetization Strategy. For example, if you have declared the Monetization Strategy for a Pack as Usage-based, you cannot then add a Revenue-sharing, Transactional or Non-monetized Usage Plans for the same Pack.

DigitMarket™ API Manager allows you to create multiple plans in the case of a Usage-based and Non-monetized plan. It, however, allows only a single plan for Revenue sharing and Transaction-based pricing strategy.

1.1.3.6. Gateway¶

An API Gateway is a networking component that performs a number of functions including Transformations, Rate Limiting, Throttling, Data Recording, and capturing log information for reporting and Analytics. The Gateway helps control traffic and applies security to your APIs.

At its core, the Gateway acts as a proxy, dissociating your back-end systems from the APIs designed for consumers. This ensures that the consumer can go about their development activities unaffected by back-end updates of the API. It also allows API developers to focus on improving API interfaces without affecting the back-end systems that serve data.

The API Gateway performs the following important functions:

Data Routing - accepts requests made to an API and routes them to the real or target endpoints.
Security - acts as a Proxy to the real endpoint to protect exposed back-end systems against attacks such as malicious code injections to provide a secure platform for accessing APIs
Authentication and Authorization - provides access control by verifying client ID and secret keys and other credentials using Basic Authentication and OAuth Server methods.
Traffic control - Manages API traffic inflow by enforcing usage limits based on Rate Limiting and Throttling
Data Transformation - transforms back-end systems into APIs that are in app-friendly formats
Performance - maximizes API and client application efficiency while minimizing API downtime
Data Logging - allows event recording for analysis, reporting, and audit

DigitMarket™ API Manager uses an API Gateway as the exposure endpoint ensuring you leverage from both all-round policy management and runtime policy enforcement capabilities of a Gateway, and at the same time derive benefits from the core functionality of API security offered by a proxy.

Fig. 1.5 API Gateway

The API Gateway handles security for APIs at two levels:

Message-level - Message-level security works at providing end-to-end message security to ensure confidentiality and integrity of a message over its full route starting from the sender through its intermediaries and until it reaches the recipient.

DigitMarket™ API Manager provides message-level security via Basic Authentication, OAuth 2.0, and WS Security (SOAP).
Transport-level - Transport-level security provides point-to-point Security for transmission of the message over a network using cryptographic exchange of data between the server and client endpoints.

DigitMarket™ API Manager implements Transport-level security using Two-way SSL over HTTPS.

At the message-level, the Gateway handles message security at two levels:

Policy-level
Endpoint-level

To understand the difference between the two message-level security, take a look at the table below:

Table 1.1 Parameter Description¶
Policy-level security	Endpoint-level security
Secures messages between the application (client) and API Gateway (server)	Secures messages between the API Gateway (client) and the exposed services (server)
Authentication possible through HTTP Basic Authentication, OAuth 2.0, WS Security (SOAP)	Authentication possible through HTTP Basic Authentication
Usage Limit configured as Usage Policy and attached to Usage Plans at Proxy Endpoint-level	Usage Limit configured as Usage Policy and attached to Real Endpoint as Part of Endpoint configuration and applies to the backend as a whole
Applied by the Policies at runtime to the plans they are attached to	Applied for all service requests regardless of the policies attached to plans

1.1.3.7. Authentication¶

DigitMarket™ API Manager uses Auth Server (Authentication Server) for controlling access to backend web services; to ensure that only API calls with valid authenticated credentials are able to access your APIs.

For Authentication, DigitMarket™ API Manager uses the following Authentication methods:

Basic Authentication
OAuth 2.0
WS security
Pass-through Authentication
API linked to Backend

Basic Authentication

Basic authentication enables you to require a client to provide credentials, in the form of a user name and password, to make a request call. The credentials in the message header is validated at the Subscription-level by the Gateway. A request message from a client must contain the user name and password fields in the request header. The user name and password are encoded before being added to an HTTP header to ensure privacy. For example, the user name: John and password: Timbuktu when encoded as a sequence of base-64 gives the result as: Sm9oblRpbWJ1a3R1.
OAuth 2.0

OAuth is an authorization framework that allows access to secure resources for third-party applications on behalf of Resource/Operation owners. It is an open standard that works over HTTP for authorizing specific users with access tokens to make a request for a Resource/Operation. To get complete information on OAuth and supported OAuth types, visit ‘Using OAuth in DigitMarket™ API Manager’ below.
WS security

WS Security uses authentication to incorporate message-level security for SOAP messages. The credentials in the message header is validated at the Gateway-level. It ensures the safety of messages exchanged between a SOAP API Resource Endpoint and the client.

SSL security is limited to creating a secure channel through which the request and response messages flow. Being a transport-level security, it is incapable of differentiated protection like when only a part of the message needs to be protected with encryption or digital signature. WS Security allows you to provide differentiated security. Differentiated protection may become necessary when parts of a message that does not need protection need to be modified by an intermittent player; like when there is a need to change the message header or body while protecting sensitive data, such as credit card details through encryption.
Pass through Authentication

When pass-through is used as an authentication method, the Gateway (at the subscription-level) does not authenticate the credentials that the user may provide and passes them directly to the API endpoint or the backend server for validation.
API Linked to Backend security

When Endpoint security for an API is linked to its backend, the credentials required to make a request call to the API is replaced at the Subscription-level by the Gateway with the security applied from its backend for authentication. What this implies is that it ignores the security applicable at API subscription-level and enforces security applicable at the API endpoint or backend-level.

Using OAuth in DigitMarket™ API Manager

The idea behind OAuth is to provide a standard way for third party applications to access protected resource without sharing user credentials. For instance, if you have a user account with Flickr - a popular photo sharing web site (in this case: a resource server) - and suppose that you have quite a few photos uploaded to the site including some very private pictures (you are the resource owner and the user). Now, you want to authorize an online content publishing web site (client) to access only some of your pictures for a limited period. Through OAuth authentication, Flickr can ensure that the client site has the right credentials (authentication) to access the content. It also ensures that they get your approval before presenting filtered content (authorization) on the client site. Contrast this with providing your credentials (user name and password) to a client app to access the resource server on your behalf. The client app will then have the same access rights as you would have had, in which case the client will also have access to your private pictures. Since OAuth is able to restrict access to your private resources, it protects any sensitive data that the user would not want to reveal.

DigitMarket™ API Manager supports OAuth as an authentication mechanism for exposed consumer APIs and can be integrated with any OAuth Service Provider. Additionally, a standard OAuth server implementation comes bundled with DigitMarket™ API Manager. DigitMarket™ API Manager uses OAuth2.0 protocol, which is the industry-standard protocol for authorization.

Following are some technical terms used in this section:

Access Token - string of characters used instead of user name and password for accessing resources
Authentication - the process of verifying the identity of a user by obtaining user credentials, such as User ID and password.
Authorization - the process of allowing authenticated users access to their resource by checking if they have access rights for the resource.
Authorization Grant - credentials used as an authorization to obtain access token
Authorization Grant Types - types of Authorization Grants used in OAuth 2.0
OAuth Server - the server that generates access tokens
Client/Client Application - an “application” that runs on a mobile device or web application. For purposes of this documentation, a client application is an application that is registered in the DigitMarket™ API Manager Developer Portal.
Client ID - Client ID is a publicly exposed string that is used by the service API to identify the application, and is used to build authorization URLs that are presented to users.
Client Secret - Client Secret is used to authenticate the identity of the application to the service API when the application requests access to a user’s account, and must be kept private between the application and the API.
Scope - allows user to choose the subscription to consume the APIs.
End-user - the user of a client application
Refresh Token - string of characters used to obtain a fresh access token after the expiry of the current access token
Resource - protected data owned by the resource owner, such as bank account information

The tables below outline activites related to OAuth authentication.

administrative activities related to Publisher and Developer portals.

Table 1.2 OAuth Administrative Activities¶

Sl. No. Task Where Documentation Path

The Application Developer registers their application Developer Portal Developer portal > Manage Applications > Add an Application

The Publisher user approves the application Publisher Portal Publisher Portal > Manage Approvals

The Application Developer receives the Client ID and Client Secret Developer Portal Developer portal > Manage Applications > View Application Details

The Application Developer manages their Access Tokens Developer Portal Developer portal > Manage Applications > Get Access Token

The Publishers manage their Developers’ Access tokens Publisher Portal Publisher Portal > Manage Access Tokens

activities related to consuming the exposed APIs from Developer applications through the DigitMarket™ API Manager Gateway.

Table 1.3 OAuth Gateway Activities¶

Sl. No. Task Documentation Path

Making authenticated requests Introduction > Key Concepts > Making authenticated requests

Gateway OAuth APIs for Access Token management Gateway OAuth APIs

Roles in OAuth 2.0

OAuth defines four roles:

Resource Owner: In a general sense, the resource owner is the end-user who authorizes an application to access their account. In the context of DigitMarket™ API Manager, the resource owner is the publisher.

Client: The client is the application that wants to access the end-user’s account. Before it may do so, the end-user must authorize it, and the authorization must be validated by the API.

Resource Server: The resource server stores protected resource and handles authenticated requests after the application has obtained an access token.

Authorization Server: The authorization server verifies the identity of the user, and then issues access tokens to the application.

Tokens

There are two token types used in OAuth: Access Token and Refresh Token

What is an Access Token?

An Access Token is a string of characters representing credentials used to access a protected resource. DigitMarket™ API Manager has UIs that allow Publisher users to view and revoke access tokens and Developer users to generate, view and revoke access token.

What is a Refresh Token?

A Refresh Token is a string of characters representing credentials used to request Access Token when the current Access Token becomes invalid or its term expires. Generally, a Refresh Token is sent along with an Aaccess Token.

What is a token endpoint?

A token endpoint is the URL used by clients to obtain the access token from the Authorization server.

Supported OAuth Grant Types

DigitMarket™ API Manager supports the following OAuth 2.0 Grant Types:

Client Credentials

The client application sends its Client ID and Client Secret in its request to obtain the access token. Steps involved in the Client Credentials flow are as follows:
1. The Publisher portal provides the client with its Client ID and Client Secret.
2. The client requests an Access Token from the Authorization Server’s token endpoint by including the credentials in the request.
3. The Authorization Server authenticates the client and validates the credentials, and if valid, issues an Access Token.
Password

The Password Grant Type is suited in cases where the Resource Owner has complete trust in the client application. In this grant type, the application developer provides the user name and password, which the client application uses to send an access token request to the authorization server.

The flow is captured in the steps given below:
1. The application developer provides the client with its username and password.
2. The client application requests an access token from the authorization server’s token endpoint by including the credentials.
3. The authorization server authenticates the client and validates the credentials, and if valid, issues an access token and a refresh token.
Refresh Token

Note that Refresh Token Grant Type works in conjunction with Password Grant Type and so it needs a Refresh Token from the Password Grant Type to work.

Refresh Token Grant Type works as follows:
1. The Access Token expires after term expiry or invalidation error. The client needs to request a new access token by authenticating with the authorization server and presenting the Refresh Token as derived from the Password Grant Type against the expired Access Token.
2. The Authorization Server authenticates the client and validates the Refresh Token, and if valid, issues a new Access Token.

Multi-Scope OAuth Support:

DigitMarket™ API Manager provides Multi-Scope OAuth support for applications registered under the Developer portal. Multi-Scope OAuth support allows the user to choose the subscription (defined with the plan id) that can be consumed by the application from the available list of subscriptions. When enabled, certain restrictions will prevent the user from using the same subscription key to access all the subscriptions under that user for a particular application.

Using an access token, an application can consume all or selective number of subscribed plans. Suppose an application A1 has subscribed to Plan P1, Plan P2 and Plan P3. Using the access token, by default the application A1 will be able to consume all the three plans - P1, P2, P3. With multi-scope OAuth support, the application will have the option to choose which plans to consume among the three(for eg. application can choose to consume Plan P1 and P2 but not P3). DMAPIM also allows Open Scope support (also known as Read scope) that lets users access all the scope under them for a given application without any restrictions.

Multi-Scope OAuth support for applications is useful when there are multiple users accessing a single application, and certain services need to be allowed/restricted to some of those users. Let us suppose that two users namely an Admin and a Developer are accessing the same application to consume certain services. The roles and capabilities of both these users are different. The scope of both these users may vary according to their roles. In such cases defining a scope will allow/restrict services to the application users (Admins and Developers) based on their roles. If a Developer wants to consume a service, they need to define a scope along with their credentials to generate a token to consume the services. Similarly a different scope can be defined for the Admin users. The user who wants to access the service, will provide their user credentials along with the scope. If the provided credentials are valid, they need to pass the scope details to generate an Access Token. The Gateway will validate the scope along with the Access Token. If the token and scope is valid, the user can access the required services. If the scope is invalid (for eg. trying to access a service with the wrong scope), the Gateway will throw an error.

OAuth workflow

The OAuth workflow in DigitMarket™ API Manager can be summarized as below:

The application developer registers an application in the DigitMarket™ API Manager Developer Portal
After the application is approved in the Publisher portal, the Developer Portal displays the generated client ID and client secret
Depending on the OAuth Grant Type used, the client application sends the credentials and requests an Access Token:
1. For Client Credentials Grant Type, the client application sends the client ID, client secret and scope to the gateway and requests for Access Token
2. For Password Grant Type, the client application sends the user name, password and scope to the gateway and requests for Access Token
3. For Refresh Token Grant Type, the client application sends the refresh token and scope to the gateway and requests for Access Token
The OAuth Provider generates an access token and sends it to DigitMarket™ API Manager Gateway, which in turn sends it to the Client.
The Client receives the access token and uses the same in all requests to consume exposed APIs
The gateway validates the access token via the OAuth provider. If valid, the request is sent to the backend API for accessing the protected Resource. If not, the Request is rejected. Note that the access token will have an expiration.

Fig. 1.6 OAuth Workflow

Registering an Application

Before using OAuth with your application, application developers must register their client application in the DigitMarket™ API Manager Developer portal. Registering an application allows the Client to receive a set of keys called client ID and client secret, which the client requires to request an Access Token.

For detailed instructions on how to register an application, refer the following link: Add an Application in the DigitMarket™ API Manager Documentation.

Client ID and Client Secret

Once a Client is registered, the service issues ‘client credentials’ in the form of a client identifier (Client ID) and a Client Secret. The Client ID is a publicly exposed string that is used by the service API to identify the application. The Client Secret is used to authenticate the identity of the application to the service API when the application requests access to a user’s account, and must be kept private between the application and the API.

For detailed instructions on how to access Client ID and Client Secret for an application, refer the following link: View Application Details in the DigitMarket™ API Manager Documentation.

Revoking an Access token

API Publisher users and Developer users can revoke an access token, which in effect cancels or invalidates the access token from the Publisher portal and Developer portal respectively. Besides, you can revoke an access token from within your application using the appropriate code.

Note

Revoking an access token deletes it from the system and the access token cannot be used again.

Making Authenticated Requests

Generate an access token using one of the Gateway OAuth APIs. To consume an exposed API, you should include the generated access token in the Authorization field of the HTTP header of your request:

Authorization: Bearer <access token>

For the interface specifications of DigitMarket™ API Manager OAuth APIs, visit: Gateway OAuth APIs

Two-way SSL security

To ensure confidentiality and data integrity, you can configure a secure connection between the API provider and API client using two-way SSL security. In two-way SSL security, both the client and server present a certificate to prove their identity to the other party. In addition to the server authentication as used in SSL security, two-way SSL security includes a client authentication also that verifies the client certificate.

Server authentication

The Server authenticates itself to the client using a digital certificate and digital signature. The client uses the certificate to validate the server’s identity. The certificate contains a public key and cryptographic algorithm used in SSL communication.

Client Authentication

The client authenticates itself to the server to assure the server that it is communicating with the right client. Client certificate contains the basic information that identifies the client and the digital signature verifies validity of this information. Client authentication becomes a necessity when the server should accept connections only from a certain group of users.

Digital Signature

Digital Signature is the value attached to information using cryptographic algorithm to ensure that the message originated from the signer has not been altered from its original form. The certifying agency issues a Digital certificate; that is basically a text file with a digital signature encrypted in it. This file accompanies the actual message through its traversed route. The encryption of the certificate by a certifying agency is called digital signature.

Anybody can decrypt the encrypted certificate but only the certifying agency can encrypt the certificate. Every browser has a list of certifying agencies. The digital signature is decrypted by the browser using the public key to identify the issuing authority. When the browser decrypts the digital certificate using the public key, it will know if the certificate is legit. A certificate can be self-signed but since no browser will recognize it (as the certificate will not be present in their browser’s list of certifying agencies), it will not be legit.

Fig. 1.7 Digital Signature

How do SSLs work?

Security based on SSL uses a public-private key pair to encrypt and decrypt messages exchanged between the server and client. Two-way SSL involves client-to-server and server-to-client authentication flows. The sender encrypts the message using the recipient’s public key. The recipient decrypts the message using its private key.

Fig. 1.8 SSL public-private keys

Following is the server authentication flow where the client verifies the authenticity of the server:

The user’s browser (client) connects to a web application (server) that is secured with SSL (https). The browser requests the server to identify itself.

The server sends a copy of its SSL certificate, including the server’s public key.

The browser checks the certificate root against a list of trusted Certifying Authorities to see if the certificate has not expired, unrevoked, and that it is valid for the website it is connecting to. If the browser trusts the certificate, it creates and encrypts a symmetric session key using the server’s public key and then sends it back to the application server.

The server decrypts the session key using its private key and sends an acknowledgment to the browser, which is encrypted with the session key that allows the browser to begin the session. From there on until the end of the session, the server and the browser will exchange data using encrypted messages.

During SSL authentication, the client and server compare cipher suites and establish agreement on the cipher suite that they will use for the session. Once the server and client have been authenticated, they use algorithms from the common cipher suite to encrypt and decrypt data exchanges for the rest of the session.

Fig. 1.9 SSL Authentication

1.1.3.8. XSS safety¶

DigitMarket™ API Manager protects the Developer portal from cross-site scripting, such as code-injection attacks that occur when an attacker uses a web application to send malicious code.

When XSS safety is enabled, DigitMarket™ API Manager sanitizes the user input and removes any malicious content before storing it in its database. When XSS safety is disabled, DigitMarket™ API Manager does not enforce the XSS safety feature and stores user input into the database without making any changes.

XSS safety feature is configurable from the properties file. Refer the DigitMarket™ API Manager installation guide to learn more on how to enable XSS safety.

Note

XSS safety is currently supported for only Developer portal.

DigitMarket™ API Manager covers the following XSS vulnerabilities:

Risky HTML elements in user input
Event handlers (such as when a form is clicked and an onClick() JavaScript event is triggered)

DigitMarket™ API Manager filters out risky tags that can find its way through user input fields wherever they are found in the Developer portal. The allowed HTML, CSS elements and URL protocols are given below:

Allowed inline formatting elements
b ,i, font, s, u, o, sup, sub, ins, del, strong, strike, tt, code, big, small, br, span, em

Allowed block elements
p, div, h1, h2, h3, h4, h5, h6, ul, ol, li, blockquote

Allowed URL protocols
http, https, mailto

Table 1.4 Allowed CSS elements¶
Allowed CSS elements	Allowed CSS elements	Allowed CSS elements	Allowed CSS elements
-moz-border-radius	border-bottom-width	font-style	pitch-range
-moz-border-radius-bottomleft	border-collapse	font-variant	quotes
-moz-border-radius-bottomright	border-color	font-weight	radial-gradient()
-moz-border-radius-topleft	border-left	height	rect()
-moz-border-radius-topright	border-left-color	image()	repeating-linear-gradient()
-moz-box-shadow	border-left-style	letter-spacing	repeating-radial-gradient()
-moz-outline	border-left-width	line-height	rgb()
-moz-outline-color	border-radius	linear-gradient()	rgba()
-moz-outline-style	border-right	list-style	richness
-moz-outline-width	border-right-color	list-style-image	speak
-o-text-overflow	border-right-style	list-style-position	speak-header
-webkit-border-bottom-left-radius	border-right-width	list-style-type	speak-numeral
-webkit-border-bottom-right-radius	border-spacing	margin	speak-punctuation
-webkit-border-radius	border-style	margin-bottom	speech-rate
-webkit-border-radius-bottom-left	border-top	margin-left	stress
-webkit-border-radius-bottom-right	border-top-color	margin-right	table-layout
-webkit-border-radius-top-left	border-top-left-radius	margin-top	text-align
-webkit-border-radius-top-right	border-top-right-radius	max-height	text-decoration
-webkit-border-top-left-radius	border-top-style	max-width	text-indent
-webkit-border-top-right-radius	border-top-width	min-height	text-overflow
-webkit-box-shadow	border-width	min-width	text-shadow
azimuth	box-shadow	outline	text-transform
background	caption-side	outline-color	text-wrap
background-attachment	color	outline-style	unicode-bidi
background-color	cue	outline-width	vertical-align
background-image	cue-after	padding	voice-family
background-position	cue-before	padding-bottom	volume
background-repeat	direction	padding-left	white-space
border	elevation	padding-right	width
border-bottom	empty-cells	padding-top	word-spacing
border-bottom-color	font	pause	word-wrap
border-bottom-left-radius	font-family	pause-after
border-bottom-right-radius	font-size	pause-before
border-bottom-style	font-stretch	pitch

1.1.3.9. LDAP support¶

LDAP is a Lightweight Directory Access Protocol used to access identity-related information from an enterprise server/servers with the intent of allowing users to be authenticated using LDAP. One or more LDAP servers contain the data that the client connects to for authentication and for getting additional user information.

In DigitMarket™ API Manager, LDAP is used as an alternative method of authenticating users.

There are two ways users can be added to LDAP in DigitMarket™ API Manager.

Add users manually to LDAP from the Publisher Users screen (for Publisher users) or Developer Users screen (for Developer Users). Use the New User from LDAP button present on each screen to add users.
Enable an option to add users automatically from LDAP when users log in via LDAP.

Users added in both of the above cases are enabled for LDAP authentication. In both the above cases, DigitMarket™ API Manager allows roles to be added via its “Fetch Roles from LDAP” plugin.

To learn how to configure LDAP support, refer the DigitMarket™ API Manager Installation Guide.

To learn how to write and configure the LDAP plugin, refer the “Fetch Roles from LDAP” Plugin Guide.

1.1.3.10. Usage Limits¶

Setting limits to the number of requests that subscribers can make to back-end resources/Operations helps lower risks of API downtime. It protects back-end APIs from malfunctions that can arise due to excessive traffic.

You set Usage limits using Rate Limiting and Throttling Policies and attach them to the subscribed Usage Plans.

Rate Limiting

Setting Rate Limits is a server-side control imposed on the number of request calls coming in at a rate faster than what is allowed. Rate Limiting basically puts a limit on how many request calls can be accepted within a specified period. Any message beyond the predefined limit is rejected. For example, a client can be allowed to do 300 requests every 5 minutes, 3000 requests every hour or 12000 requests per day. Anything in excess of these limits returns an error and forces the client to retry after the limit period is reached.

Fig. 1.10 Rate limiting

Throttling

Throttling is similar to Rate Limiting except that unlike Rate Limiting, the number of requests that exceed the permitted limits are not rejected but held in a queue. The pending requests are serviced in the next time slot. Once the call limit has reached, a delay on the client machine is inserted on subsequent calls to push the requests to the next time slot. For example, suppose you have a scenario where a developer has produced a poorly written app that ends up making excessive calls to an API, resulting in an overload. Using DigitMarket™ API Manager you can use predefined policies to throttle the incoming calls to a manageable limit by placing the excessive calls in a queue until the app is fixed and the next call is served.

Fig. 1.11 Throttling

1.1.3.11. Concurrency Limit¶

Concurrency limit is the MCT (Maximum Concurrent Connection) value or the maximum number of simultaneous API requests that is allowed within an API for an API Resource/Operation at any given time. It comes into effect when the messages are ready to be send to the backend.

1.1.3.12. Usage Policy Library¶

Usage Policies are configurations that enforce Usage Limits on the amount of traffic an API should receive. Usage Policies are applied on APIs through the Gateway, which enforces the Rate Limits and Throttling limits to manage traffic. The objective behind using Usage Policies is to safeguard underlying systems from traffic overload.

DigitMarket™ API Manager provides a Library to store and use Usage Policies. You can create new Usage Policies, modify or delete existing policies and enforce them by propagating them through the Gateway.

You can create Usage Policies based on the kind of restriction(s) you wish to impose on API calls. The Policies can be either Rate Limiting or Throttling. When you define Usage Policies, and store them in the Library, you can attach them to Usage Plans. At the time of creating Usage Plans, DigitMarket™ API Manager gives you the option to choose the Usage Policy that you wish to apply to a Plan. You can select a Plan-level policy that applies to all the resources/operations under a plan or you can attach Policies individually to each Resource.

1.1.3.13. Transformations¶

DigitMarket™ API Manager through its Gateway provides a central transformation point to:

carry out custom content modification, injection and removal, whereby Request and Response headers and payloads can have content modified, added or removed
change message exchange protocol from REST to SOAP and vice-versa. Changing message protocol enables JSON to XML and XML to JSON conversions.
accept user-provided JavaScript, based on which, it enables transformation of REST with XML payload into SOAP request and vice versa, and REST with JSON payload into SOAP request and vice versa.

DigitMarket™ API Manager handles Transformations at two levels:

API Level - Transformations handled for the API as a whole, which includes all the Resources/Operations that form part of that API.
Resource/Operation Level - Transformation is performed for every Resource/Operation Endpoint.

At runtime, when Transformation is applied on a message, say a request call to an API Resource/Operation, initially, the message goes through an API-level Transformation and if the Resource/Operation-level Transformation is applicable for the Resource/Operation, then the Resource/Operation-level Transformation is applied to the message.

Note

DigitMarket™ API Manager does not validate the user-provided scripts nor does it store the scripts for future use. It is hence important for the user to validate the scripts before use and preserve them for any future use.

1.1.3.14. Data Recording¶

The Data Recording feature provides a means to log data from the API Requests and Responses. Data so recorded can be used for analytical and billing purposes. The user can determine whether they wish to log the data and if so, they can also specify the fields to add, remove or mask (to conceal a field having sensitive data) from the message payload and header while recording. If data recording is enabled, data is logged in both the application logs and transactional database. Based on a default template provided, the user can upload a script for each resource/operation and use the payload as the input in the uploaded script.

1.1.3.15. Life cycle of Artifacts and Approval Workflows¶

APIs and other related artifacts have their own life cycles independent of the back-end service on which they rely upon.

DigitMarket™ API Manager provides you the tools to manage life cycles of not just APIs, but also other artifact types like API Packs, Usage Plans and Usage Policies.

In DigitMarket™ API Manager, an artifact’s life cycle has the following main States:

Table 1.5 Artifact Lifecycle¶
State	Symbol	Description
Draft		a freshly created artifact. If it’s an API, or API Pack, it is not visible to consumers yet. None of them are deployed to the API Gateway.
Approved		an artifact that has been approved. If it’s an API, it is ready to be bundled into a Pack and monetized. Other artifacts are ready to be deployed to the server. Once deployed, an API Pack is available in the API Store for developers to subscribe.
Published		an artifact that has been published after it is approved and successfully deployed to all Gateways.
Deprecated		an artifact though active, is marked for retirement or is close to being put out of use. Deprecated APIs and API Packs stay active on the server for existing subscribers but is unavailable from the Store for new subscribers.
Retired		an artifact that is no longer in use in the Publisher or Developer portal.

There are other intermediary states that supplement the main States:

Submitted for Approval - - When an artifact in Draft State is sent for approval to progress to the Approved State.
Submitted for Deprecate - - When an artifact in Approved State is sent for approval to progress to the Deprecated State.
Submitted for Retire - - When an artifact in Deprecated State is sent for approval to progress to the Retired State.
Approved, Awaiting Approval for Editing - - When you open an artifact for Editing using the Open for Editing feature after it’s Approved.
Published, Awaiting Approval for Editing - - When you open an artifact for Editing using the Open for Editing feature after it’s Published.

Note

An artifact goes into intermediary states only when Automatic Workflow for the artifact has not been enabled from the Global Configurations menu.

An API, API Pack, Usage Plan or Usage Policy has to be sent for approval to progress to its next State, which is when it appears in the Approval Requests list. Once a Publisher user approves the artifact, it progresses to the next State in its life cycle.

Fig. 1.12 Lifecycle

1.1.3.16. Gateway Synchronization¶

Gateway Synchronization is an act of propagating configurations from the portal to the Gateway to make them operational at runtime.

There are two methods that the Gateway employs to affect Synchronization, namely Manual Sync and Auto Sync. The following table presents the concept and comparison in each case:

Table 1.6 Artifact Lifecycle¶
Manual Sync	Auto Sync
Manual Sync applies to configurations that the user needs to propagate to make them operational in the Gateway.	Auto Sync applies to certain configuration changes that get propagated automatically to the Gateway on the user submitting these changes.
Manual Sync is required on Approved API Versions, Approved Usage Plans and Approved Named Usage Policies.	Configuration changes that are automatically synced include changes made to Backend Endpoints, Global Configurations for Fault and Response codes and Response messages, and Subscription-level Configurations
DigitMarket™ API Manager enables the user to ensure data integrity is maintained in case there is an error in synchronization.	Data integrity is handled internally
Manual Sync has an associated Manual Rollback feature that allows the user to roll back to an earlier working instance of an Approved API Version, Usage Plan or Named Usage Policy	No Rollback is required as Auto Sync occurs without user intervention

Rollback

DigitMarket™ API Manager supports restoration of the Gateway to a previously defined state. To achieve this, you can use the Rollback option after changes are synched from the portal, and in case you need to revert new configurations.

1.1.3.17. User Roles and Portal Visibility¶

DigitMarket™ API Manager makes use of four pre-defined user roles or user types to allow access-based control on the Publisher portal. These user roles are:

Admin user
Business user
Technical user
Approver

Each of these user types has different Visibility options and part of the portal is either visible or not visible depending on the user role.

Additionally, DigitMarket™ API Manager enables the user to define Publisher portal user groups and Developer Portal user Groups. The user can associate Publisher portal users with one or more Publisher user Groups and Developer portal users with one or more Developer user groups. You can decide which Groups you want to allow interacting with what part(s) of the portal using the Visibility feature. For example, if you have two Publisher groups named API Designers and API developers and a user X that you have assigned to the API Designers group and a user Y assigned to the group API developers. If you want an API named WebText to be made visible only to user X and not user Y, you must set visibility for the API WebText to the group API Designers and remove the visibility to the group API developers.

The portal Visibility feature allows you to set visibility for the following artifacts:

APIs
API Packs
Usage Plans

The following table shows the implications of the visibility feature for Publisher and Developer user Groups:

Table 1.7 Implications of Visibility¶
Artifact Type	Publisher user groups - applicability	Developer user groups - applicability
API
API Packs
Usage Plans

1.1.3.18. Search¶

The Search feature is a quick and convenient way of locating an API, API Pack or Usage Policy without the user having to browse through the list pages. The user can conduct searches on following artifacts:

APIs
API Packs
Usage Policies

The Search functionality is available from the respective artifact’s list pages. Search accepts user input as texts and does a thorough search on the database for matches before displaying the search results.

Some salient features of the search functionality are:

A Search on an API includes data from all versions of the API.
Search respects the visibility settings and displays results from only those artifacts that are available to the user for viewing.
Search returns results even when the search term is a fragment of the whole term. For instance, a search for the word “contract” returns matches for “contract” as well as “managecontract”.
When a search match lies in a paragraph or a block of text as in the case of Overview descriptions, the search results display five words each from the beginning and end of the text block or para.
The search results include the lifecycle state of the artifact to indicate whether the artifact is in its draft, approved, published, deprecated, or retired state.

1.1.3.19. Configurable Workflows¶

DigitMarket™ API Manager allows the user to configure approval workflows for all artifacts that have a lifecycle. The user can enable approval workflows for APIs, API Packs, Usage Plans and Usage Policies. Approval workflows are applicable to admin, approver and Business user roles. When you enable approval workflow for an admin user, approver or business user by turning the workflow toggle state to green, the user enjoys automatic approval workflow in which the user does not await approval from the approver and the state transitions to its next state in the lifecycle automatically. Disabling the approval workflow by switching the approval toggle state to red returns the user role to the default state for approvals, wherein an artifact needs to get the approval from the approver before advancing to the next state in its lifecycle. For instance, if a user enables approval workflow for APIs for an admin user role, the admin user does not have to send an Approved or Published API for editing request as the workflow skips the send for approval flow. The API becomes instantly available for edit through the Open for Editing option in the Action menu.

1.1.3.20. Email Notifications¶

The Email Notifications feature supports SMTP or SMTPS server that enables specified email recipients to receive email notifications about events. The user receives notification for the following list of events:

Subscription request - when a developer user sends an approval request for subscribing to an API Subscription Plan (Usage Plan) in the Developer portal.
Subscription cancellation - when a developer user unsubscribes from a Subscription Plan
Approval workflow - when an approver approves or rejects an artifact (except approvals/rejections of registration application received from developers).
Reject comment - when an approver creates a reject comment for approval request.
Addition of a new developer user - when a new developer user is added from the publisher portal
Addition of a new Publisher user - when a new publisher user is added from the publisher portal
Forgot Password - when a user receives a password reset link in the user’s email associated with the user name

1.1.3.21. Exporting and Importing Data¶

DigitMarket™ API Manager enables you to export and import data for new and existing versions of all artifacts (APIs, API Packs, and Usage Policies) that have an Approved or Published state and from other entities, such as Backends and Gateways.

There are three modes for exporting and importing data:

Artifact-specific Export and Import - The user exports and imports data from individual instances of an artifact type.
Artifact type-specific Export and Import - The user exports and imports data from all approved and Published versions of a specific artifact type.
Global Export and Import - The user can select more than one artifact type for which approved and published versions need to be exported or imported. Global Export and Import feature includes options for importing and exporting other entities, such as Backends and Gateways. When you export, data from selected artifact types or other entities get stored in a composite file named Export.zip.

The table below shows availability of export and import modes for each artifact/entity type:

Table 1.8 Parameter Description¶
Artifact/Entity type	Artifact specific	Artifact type-specific	Global
API
API Pack
Usage Plan
Usage Policy
Backends
Gateways

Export

The user can access the export option from the following screens/pages: a) Artifact configuration page b) Artifact list page c) Global export from the Export & Import menu option

While exercising the export option from the list or global export, only those artifacts that are visible to the logged-in user - as per the visibility settings - is available for export.

The individually exported files have a structure as below: A master folder that contains a folder with name ‘Export.zip’, which has a subfolder with the API Type (i.e., REST or SOAP), which has a folder with the API name, which again has one folder each for each of version the the API has, and inside which there is a ‘data.json’ file with the API details and other supporting files, such as the YAML file (REST), or WSDL and XSD files (SOAP).

The Zip file to which the data gets exported into contains the data.json file. The data.json file contains information about the artifacts in JSON format.

Import

The user can access import option from the following screens/pages: a) Artifact configuration page b) Artifact list page c) Global export from the Export & Import menu option Import is a single atomic transaction. It updates either all content in the database or none at all.

Import creates a new revision for the imported artifacts (where applicable), and on successful completion puts all artifacts that have lifecycle states into the Approved state.

While performing the import from the artifact’s configuration page, list page or the global export option, the import includes only those artifacts that are visible to the user doing the import irrespective of whether an artifact is present in the target server or not.

For importing data from approved and published APIs, API Packs, and Usage Policies and other entities, such as Global Configurations, Backends and Gateways, the user can use two methods:

Full Import
Delta Import

Full Import - enables you to override existing data, whereby the existing data is removed and replaced by the data from the imported file. After a full Import, the existing artifacts shall be deleted from the present deployment and the artifacts in the imported file shall be populated. SSL certificates, if any, have to be configured manually.

Fig. 1.13 Full Import

A Full Import procedure ascertains if a matching artifact name and ID exists in the target server.

If an artifact exists in the target server: A full import removes all related data of the artifact except the ID, and updates the artifact data with imported details for the artifact.
If an artifact does not exist in the target server: A full import creates a new artifact with the details from the imported ZIP file.

Delta Import - retains the existing information and only updates new data that is present from the imported file. A Delta Import has the following impact on the deployed files:

If an artifact item exists in the target server: A Delta Import updates all common aspects between the imported details and the target repository with the imported details for the artifact. It retains the IDs of the artifacts.
If imported artifact items do not exist in the target server: A Delta Import creates a new item with the imported details from the ZIP file and retains the items that are present in the target repository but not present in the imported file.
If artifact item exists in the present instance but not in the imported file, they shall be left untouched.

SSL certificates, if any, have to be configured manually.

Fig. 1.14 Delta Import

When the user uses the Global import from the Export & Import menu option, import of artifact types follow the order given below (based on the availability in the ZIP file): 1. Global Configuration 2. Backend 3. Gateways 4. API 5. Usage Policy 6. API Pack with Plans

The implications of each import method on import modes described earlier are as tabulated below:

Table 1.9 Import Implications¶
Import mode	Full Import	Delta Import
Artifact specific Import	The existing artifact content is deleted and the artifact content from the imported file is populated.	If the artifact being imported already exists in the present portal instance, it shall be updated with the details in the imported file. artifacts present in the present portal instance but not in the imported file shall be left untouched. If the artifact being imported does not exist in this instance it shall be created.
Artifact type-specific Import	All existing artifact instances are deleted and the new artifact instances from the imported file is populated.	If the artifacts in the artifact type being imported already exist in the present portal instance, they shall be updated with the details in the imported files. artifacts present in the present portal instance but not in the imported file shall be left untouched. If the artifacts in the artifact type being imported do not exist in the present portal instance they shall be created.
Global Import	The existing artifacts shall be deleted and the artifacts in the imported file shall be populated.	If an artifact with a same name and version is found in the imported file, and the data in the imported file has changed, the changes are added to the existing data in the artifact. If an artifact with a new name or a new version is found the same is added to the portal instance. If an artifact name and version from the presently deployed instance is not found in the imported file, the artifact is left untouched.

Fig. 1.15 Full Import Vs Delta Import

1.1.3.22. Developer Portal¶

The Developer portal is a web portal for app developers. The portal enables them to discover, test and adopt APIs for use in their applications. Developers sign up, explore APIs, and subscribe to Usage Plans that have the APIs they wish to consume.

The Developer portal has the following features:

API Discovery via API Store
Developer On-boarding and Sandbox Testing
Client ID and App Key Generation
Developer Administrative services - Manage Applications, Subscriptions, bookmarks, etc.
API Documentation
Discussion forum
Usage Analytics

What is an Application

An application, in the context of APIs, is a program that uses APIs to provide valuable services to its users. The developers of applications do not need to reinvent the wheel for a desired functionality. The APIs allow them to use a prime functionality that they can call into their applications. This leaves them with focusing on writing codes for the primary focus areas of their applications.

An application that helps its users find rented apartments can use a Craigslist’s API for their listings and a location mapper API like Google Maps to mark the exact location of the apartment.

What is Developer portal Customization

Developer portal customization helps you modify the look and feel of the Developer portal to make it consistent with your corporate branding and strategy needs. The tasks you can do under customization include making changes to the category hierarchies, applying background images, banners and icons to API Packs, and adding files with the help of a Content Management System. Category hierarchies allow you to change the way the Packs display in the API Store.

DigitMarket™ API Manager provides a default implementation for the Developer portal. Each publisher is provided with a copy of the default implementation of the Developer portal, wherein the HTML, CSS, JS files can be modified as and when needed.

API Store

An API Store is a Developer portal marketplace that comprises a categorized view of all API Packs that the developers can browse and search to find their favorite APIs. You can go into the detailed view for each Pack, from where you can use Sandbox to try out the APIs. The Store also serves as a link to inner pages from where developers can subscribe to an API Pack, read API documentation, and have interactions with other developers in a Discussion Forum.

DigitMarket™ API Manager allows the user to control visibility of an API Pack in the API Store, which selectively displays those API Packs that are useful to a Developer.

Fig. 1.16 Subscription

Sandbox

As an app Developer, when you learn about an API that you wish to use in your app, you’ll first want to test it out to see if the responses can be integrated to make them work with your application. DigitMarket™ API Manager provides the Sandbox environment that enables the user to do test runs on an API.

DigitMarket™ API Manager makes use of Swagger for its Sandbox UI. Swagger has a UI framework that accepts parameters and demonstrates in a Sandbox environment how an API behaves when a request is placed through its interface. Since the UI used for Sandbox testing uses standards used in Swagger Specifications as the mode for listing out resources/operations and descriptions, the user has all the Resource/Operation descriptions that is required to start trying out APIs.

The documentation that accompanies the listings allows the user to make calls from within the documentation. The API resources/operations list presented in the Sandbox UI is extracted from YAML/WSDL files (created and updated from API resources/operations list defined by API Publishers) based on Swagger Specification/WSDL. The YAML/WSDL file contains descriptions of the REST/SOAP service like Resource/Operation paths, HTTP methods (REST), parameters of path or query, response/fault codes and types, and HTTP/fault error codes.

Subscriptions

An API Subscription is created when a Developer purchases a Usage Plan against which usage is tracked and monetized. Subscribing for an API Plan typically involves a subscription fee; that is charged for the usage of APIs under that Plan, and a validity period; that defines the period for which the Subscription is valid. On the expiry of the validity period, you have the option to allow the Developer users to automatically renew a subscription. The subscription is linked to a Usage plan and hence the Developer who subscribes to a plan is bound by the usage limits applicable for the plan. In cases where the runtime API calls exceed the limit as defined in limiting policies (Rate Limiting or Throttling), the excess API calls, depending on whether Rate Limiting or Throttling is in force, are either rejected or held in a queue for the next slot.

DigitMarket™ API Manager allows you to manage Subscriptions via a module dedicated to Subscriptions.

Statistics

You can review and get insights from the Statistics provided in the Developer portal. Through charts and graphical representations, you can find the traffic generated on an API or an application, the quota usage and error and timeout representations.

The Statistics feature enables API developers to view:

Traffic by APIs
Quota Usage
Traffic by Applications
Errors and Timeouts