Creating an API Design Project

---

Log in to the platform and select “API Design Studio”:

You will be taken to the API Design Projects list screen. All the API Design project that you have access to will be listed with information on your access level, type, current status. If you would like to export the project in OpenAPI specifications, you can click on the button with a drop down symbol and select the option of json or yaml file as export file formats. 

To open the project, click on open button.

To remove the project, click on the delete button.

Creating a new API Design Project

A new project can be created by clicking on "Create" button. 

The dialog box has two options to create new project, either by importing it from an existing file containing specifications or create a new blank project, select the appropriate option and click next.

In the next screen, type of the project you want to create from the given options and either specify a name of the project to start from a blank project and click on “create" or click next to select the specifications file, in which case the name will be picked from the specifications file.

Once the project is open, you can add or edit details.

API Design Studio provides user interfaces to add or edit the parts of the API specification project.

The menu on the left, next to context action menu show the parts of the project.

The project has 3 main parts: Configs, Paths and Components.

Configs have the following sub-parts:

These details help provide a more comprehensive understanding of the different parts of the OpenAPI Specification and how they contribute to defining and documenting APIs effectively.

API Details (represents “Info” of the OpenAPI Specification)

• "title": The title of the API, which provides a brief description of what the API does.
• "version": The version number of the API, indicating the iteration or release of the API.
• "description": A more detailed description of the API, providing information about its purpose, functionality, and any specific considerations or limitations.
• "contact": Contact information for the API provider, such as an email address or URL, to enable users to get in touch for support or inquiries.
• Terms of Service: It can optionally have a link to outside url containing the terms of service
• License Information: It can optionally have a link to outside url containing the license terms for usage of this API and its description
• External Documentation: If there is any documentation available on a site outside, it can be specified here

API Security which has following options:

This part specifies the security requirements and mechanisms for accessing the API.

It defines the authentication methods, such as API keys, OAuth, or other authentication mechanisms that clients must use to access protected resources.

It outlines the steps and information required for successful authentication and access control.

• API Key: An API key is a unique identifier used to authenticate and authorize a user, developer, or calling program to an API. However, they are typically used to authenticate and authorize a project with the API rather than a human user.

The fields for this option are:

• Name of the API key, 
• Where the key is expected to be located out of query, header and Cookie can be specified
• An optional description

• HTTP: 
• Basic authentication is a simple and widely supported authentication method that uses the HTTP header to send the username and password of the client. The client encodes the credentials in base64 and sends them with every request. The server decodes the credentials and checks if they are valid. 

Here’s an example of a Basic Auth in a request header: 

Authorization: Basic bG9sOnNlY3VyZQ==

• Bearer authentication is a more advanced and secure authentication method that uses tokens instead of credentials. A token is a string of characters that represents the identity and permissions of the client. The client obtains a token from an authentication server by providing valid credentials or other information. The client then sends the token with every request using the HTTP header or the query string. The server validates the token and grants access to the API. The name “Bearer authentication” can be understood as “give access to the bearer of this token.”

• The HTTP digest authentication authenticates a user based on a username and a password. However, unlike with basic authentication, the password is not transmitted in clear text between the client and the server. Instead, the client sends a one way cryptographic hash of the username, password, and a few other security related fields using the MD5 message-digest hash algorithm. When the server receives the request, it regenerates the hashed value for all the fields as done by client and compares it with the one present in the request. If the hashes match, the request is treated as authenticated and valid.

• Mutual authentication is when two sides of a communications channel verify each other's identity, instead of only one side verifying the other. Mutual authentication is also known as "two-way authentication" because the process goes in both directions.

• OAuth2: OAuth2 security with flow options such as implicit, password, client credentials and authorisation code

OAuth 2.0 is an authorization framework that provides a standardized way for applications to obtain authorization and access resources on behalf of a user, without needing to know the user's credentials. It is commonly used for authentication and authorization in modern web and mobile applications. OAuth 2.0 supports several authentication options or grant types. Let's explore the details of some commonly used grant types:

• Authorization Code Grant:
• This grant type is recommended for web applications where the client (application) operates on a server.
• The flow involves the client requesting authorization from the user, who then grants permission to the client.
• The client receives an authorization code, which is exchanged with the authorization server for an access token.
• The access token is then used to make authorized requests on behalf of the user to the protected resources.

• Implicit Grant:
• This grant type is typically used by single-page applications (SPAs) or applications running in a web browser.
• The client requests authorization directly from the user and receives an access token as part of the response.
• Unlike the Authorization Code Grant, there is no intermediate step of exchanging an authorization code for an access token.
• The access token is directly issued to the client, which can then make authorized requests to the protected resources.

• Resource Owner Password Credentials Grant:
• This grant type allows a client to directly request an access token by presenting the user's credentials (username and password) to the authorization server.
• It is typically used in trusted environments where the client has a high level of trust with the authorization server.
• The client sends the user's credentials to the authorization server, which validates them and issues an access token if successful.
• The client can then use the access token to make authorized requests to the protected resources.

• Client Credentials Grant:
• This grant type is suitable for cases where the client application is acting on its own behalf, rather than on behalf of a specific user.
• The client directly requests an access token from the authorization server by presenting its own credentials (client ID and client secret).
• The client credentials are authenticated by the authorization server, and if valid, an access token is issued.
• The client can then use the access token to access the protected resources it is authorized to interact with.

These are some of the common OAuth 2.0 authentication options or grant types. Each grant type serves different purposes and is suitable for specific scenarios based on the nature of the client application and the authentication requirements. It's important to carefully consider the security implications and choose the appropriate grant type based on your specific use case and the level of trust between the client, user, and authorization server.

• OpenID Connect: OpenID Connect is an authentication layer built on top of the OAuth 2.0 framework. It provides a standardized way for clients to authenticate users and obtain identity information, allowing for secure and federated authentication in REST APIs. Let's delve into the details of OpenID Connect authorization for REST APIs:

• Authorization Request:
• The client initiates the authorization process by redirecting the user to the OpenID Connect Provider (OP) authorization endpoint.
• The client includes parameters, such as the requested scope (including the "openid" scope) and the redirect URI.

• User Authentication:
• The user authenticates with the OP, which could involve entering credentials or using a single sign-on (SSO) mechanism.
• The OP verifies the user's identity and determines if the user consents to the requested scope of access.

• Authorization Code Grant:
• Once the user is authenticated and provides consent, the OP issues an authorization code to the client through a redirect URI.
• The client receives the authorization code and can then exchange it for an ID token and optionally an access token.

• Token Exchange:
• The client sends a token exchange request to the OP token endpoint, including the authorization code received in the previous step.
• The client authenticates itself with the OP, typically using its client credentials (client ID and client secret).
• In response, the OP returns an ID token containing user identity information and an optional access token for accessing protected resources.

• Accessing Resources:
• With the ID token and/or access token, the client can make authorized requests to the REST API's protected resources.
• The client includes the ID token in API requests as a means of identifying the user and the access token for authorization purposes.
• The REST API can validate the ID token's signature and claims to ensure the authenticity and integrity of the user's identity.

OpenID Connect provides a standardized mechanism for authentication and user identity in REST APIs. By leveraging the OpenID Connect authorization flow, clients can obtain an ID token that securely represents the authenticated user and access tokens to interact with protected resources. The ID token helps establish trust in the user's identity, while the access token allows for secure and authorized access to the REST API's resources on behalf of the user.

Servers:

• Servers provide a list of servers that act as domains on which the APIs are deployed and accessible.

Tags:

• Tags provide a way to categorize and group related API endpoints.
• They allow you to organize the API documentation and make it easier for developers to navigate and find specific endpoints or functionalities.
• By assigning tags to endpoints, developers can filter or search for endpoints based on specific categories or functionality.

Paths

A Path is a unit of a REST API that you can call. A Path comprises an HTTP verb and a URL path that, when exposed, is combined with the base path of the API. By configuring the Path, you define how the API is exposed to your developers

• Each path represents a specific URL endpoint that clients can access to interact with the API.
• Within each path, you define the supported HTTP methods (GET, POST, PUT, DELETE) and their associated functionality.
• For example, "/users" might be a path to retrieve a list of users using the GET method, and "/users/{id}" might be a path to retrieve a specific user by their ID.

Methods

An API call specifies an HTTP method which invokes a function at the API server and gets or manipulates data.

The methods has following parts:

Summary: This provides basic details of the method such as summary of the action it does, tags if there are any, operation id that identifies an operation at server side and a description for the users.

Parameters

Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. There are several types of parameters: header parameters, path parameters, and query string parameters. Request bodies are closely similar to parameters but are not technically a parameter. Parameters allow clients to pass information to the API when making requests. The screen provides options to be specified for the data types, parameter types and the description of the parameter.

Parameters can be of following types:

• Query parameters: These are appended to the URL after a question mark "?", allowing clients to filter, search, or provide additional information in the request. For example, "?search=keyword" could be used to search for specific data.

• Path parameters: These are placeholders within the URL path itself, denoted by curly braces "{}". They are used to provide dynamic values in the URL, such as "/users/{id}" where "{id}" represents a specific user ID.

• Request body parameters: These are included in the request body and provide more complex or structured data. They are commonly used when creating or updating resources.

Body

This is the structure of the data in the request that the server expects. Body can have the type of the data and its schema. There are multiple bodies possible to be specified since Schemas can vary by media type.

The screen allows you to add bodies to the request method along with its schema and its description.

Responses: Responses are the expected responses to the API call. Each response is associated with an HTTP status code that indicates the outcome of the API request (e.g., 200 for success, 400 for client error, 500 for server error).

• Responses include a description to provide further details about the response and its purpose.
• Response schemas can be defined to describe the structure and format of the data returned by the API, typically using JSON Schema or other supported schema formats.

External Docs: In this section you can specify an optional link and description to documentation that is available outside the platform

Components

This section has a set of reusable schemas for parts of the API project. The schemas can be created for any collection of data such as business object, and referenced from Headers, Parameters, Request body or response body.

The screen has different sections for creating objects to be used in these parts.

The first option “Schema Builder” provides a screen to build the json schema since typing json schema might be error prone for some users. As the user creates schema using schema builder, the resulting schema keep updating on the right panel of screen for easy reference. The schema can viewed in either json or yaml format.

• Schemas define the structure and data types of objects used in the API.
• They describe the properties of objects, their data types (string, number, boolean, etc.), any required or optional fields, and validation rules.
• Schemas are typically defined using JSON Schema, which allows you to specify the properties, data types, and constraints of each field in an object.

Do note that the changes need to be saved with the  button. Consider saving changes often while working on the project.