Overview of Creating a REST API from Scratch
The Create REST API wizard breaks down the task of creating a REST API from scratch into logical steps. The following figure illustrates the different pages of the wizard.
Basic Information
The Basic Information page includes fields that allow you to identify, categorize, and group an API.
Technical Information
The Technical Information page includes fields that allow you to define one or more server URLs for the API. You can also define and include variables in the URLs.
You can also specify parameters for data that must be included in every request to the API. For example, if you want a specific query parameter to be included in every request, you can add a parameter of the type Query and specify the value that it must include.
Resources and methods
The Resources and methods page includes fields that allow you to define the API resources and methods, including callback methods. In this page, you can add all the resources and their methods that are exposed by the API.
At the resource level, you add a resource by defining the following properties: name, path, and supported methods. You can additionally add parameters for data that must be included in every request to that resource. For example, if the methods in a resource are invoked using URLs that have a query string; you can add a query string parameter that captures the queries sent by the clients.
At the method level, you identify a method by adding an operation id. In addition, you can add tags that help you to categorize and search for similar methods. You can also add parameters at the method level. Similar to the parameters at the API and resource levels, method parameters enable you to capture and process the data that is sent in a particular request. In the case of method parameters, the data in the request for that method is captured and processed.
Method Requests
In the request section of a method, you can define the schema for requests that contain a JSON or XML payload. As a method can support multiple content types, you need to add a content type and then define the schema supported by that content type.
You can enter a schema or select an existing schema or global schema that you have previously added on the Components page, Schemas section. You can also add a sample for the schema that you have added or selected. These samples can be used for API mocking. They can also be used by end users to get a better understanding of the API.
Method Responses
You can define responses for different HTTP status codes. API Gateway gives you the flexibility to define responses for a status codes series (such as the 2XX series or the 4XX series) or for specific response codes, such as 201 or 400.
Note:
If you have defined the response for a series and specific numbers in that series, the more specific one is used. Example: If you have added an entry for 2XX and 201, a response with the HTTP status code 200 will be the same as 2XX. However, a response with the HTTP status code 201 will pick the one that is defined for 201.
For each status code in a method response, you define the following:
Response body: you define the response body using the following fields:
Content Type: You can select from any of the content types.
Schema: You can define a schema if the response contains JSON or XML data.
Sample: The samples are used for API mocking. They can also be used by end users to get a better understanding of the API.
Header parameter: You can add a parameter to capture and process a header in the response sent by the native API.
Links: Links allow the developer of the native API to define the relationship and traversal mechanism between a response and other operations. You can include links to other methods that are related to the response. This enables an API client to dynamically navigate the methods that are exposed by the API. For example, a method that returns the temperature in Fahrenheit for a given place may also include links to methods that return: a) the temperature in Centigrade; and b) the temperature of the place on a given day of the year.
Note:
You can define the complete response, or any part of it (response body schema, header parameter, or link), in the Components page; and reuse it wherever required by giving a reference.
Method Callbacks
A callback is an asynchronous API request that originates from the API server and is sent to the client in response to an earlier request sent by that client. APIs can use callbacks to signal an event of interest and share data related to that event. API clients that are interested in an event or data related to that event, include a callback URL in the request they send to the API. For more information about Asynchronous APIs, see
Asynchronous APIs.
To enable API Gateway to process callback messages, you must configure the Callback processor settings, as explained in
Configuring API Callback Processor Settings.
If your API supports callbacks, you can use API Gateway to process the initial requests, the callback URLs sent by clients, and the response sent by the API—including the callback messages. Clients can provide the callback URL to API Gateway in any of the following ways:
Request header
Query parameter
Request body (if the response body has JSON or XML content)
You must define the relevant parameter to capture the callback URL to process it. API Gateway can wrap the client callback URLs with its own URL to process these requests if the callback URL path defined in the following formats. Otherwise, API Gateway sends the requests received from client as it receives it.
Format | Description |
{$request.query.param-name} | Where param-name is the name of the query parameter that contains the callback URL. |
{$request.header.header-name} | Where header-name is the name of the header that contains the callback URL. |
{$request.body#/field-name} | Where field-name is a field in the request body. If the field is an array, use the syntax {$request.body#/field-name/arrayIndex}, where arrayIndex is the index of the callback URL in the array. |
${response.header.header-name} and ${response.headers.header-name} | Where header-name is any of the valid header. |
${request.query.param-name} | Where param-name is the name of the query parameter that contains the callback URL. |
${response.payload.jsonPath[queryValue]} | Where queryValue is a valid JSON path expression. |
${response.payload.xpath[queryValue]} | Where queryValue is a valid XPath path expression. |
If you have enabled API Gateway to process callback messages, API Gateway wraps the callback URL provided by the client and sends an API Gateway URL to the native API. When the native API invokes the same callback URL, API Gateway processes the response and applies the policies that you have defined.
API Gateway can apply the following policies on the callback messages:
Invoke webMethods IS
Response Transformation
Validate API Specification
Data Masking
Log Invocation
Note:
These policies are applied to the immediate responses of an API request and to all its callback requests. These policies are enforced against callback request payloads.
API mocking
API mocking allows you to simulate a native API that is not available. The mock response that you define is returned to the client that invokes the API, if the native API is not available. API mocking is not available while you are creating an API. To use API mocking, you must edit the API after creating it and enable API mocking. For more information about API mocking, see
API Mocking.
Components
The Components page allows you to add reusable elements that you can use in other pages of the wizard. You can reference these global elements using the $ref variable. You can add the following global elements:
Schemas: The schema specified here can be reused in the resource and method specifications across multiple methods and resources.
Parameters: You can define parameters that can be used as API, resource, and method parameters.
Headers: You can define parameters that can be reused as header parameters at the API, method, and response levels.
Examples: You can add examples that can be reused as samples across operations in the API.
Links: You can define links that can be reused in responses. For more information about links, see
Links within
Method Responses above.
Callbacks: You can define callback methods in this page and include them in the callback section of the methods that use it. For more information about callbacks, see
Method Callbacks.
Request Bodies: You can define request bodies in this page and reuse them in methods. A request body includes the content type, a schema, and a sample.
Responses: You can define responses in this page and reuse them in methods. A response includes the content type, a schema, and a sample. It can also include header parameters and links.
Documentation
In the view mode, the Documentation page provides the following links:
Links to the Swagger, RAML, and OpenAPI versions of the API on the Integration Server.
Note:
If Cross-Site Request Forgery (CSRF) token is enabled on the Integration Server, the links to three types of APIs will not work. You must configure Integration Server to allow these links to work.
Links to download the API in the three different formats: Swagger, RAML, and OpenAPI.
In the edit mode, the Documentation page allows you to add a file that contains any documentation that you want to include with the API. This file is accessible only from API Gateway.
