API creation from scratch

Basic Information

The Basic Information page includes fields that you can use to identify, categorize, and group an API.

Technical Information

The Technical Information page includes fields that you can use 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 you can use to define the API resources and methods, including callback methods. Also, 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 properties, name, path, and supported methods. Also, you can add parameters for data that must be included in every request to that resource. For example, to invoke the methods in a resource by using URLs that have a query string. You can add a query string parameter that captures the queries that the clients send.

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. Also, you can add parameters at the method level. Similar to the parameters at the API and resource levels, you can use method parameters to capture and process the data that is sent in a particular request. For 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 must add a content type and then define the schema that the content type supports.

  You can provide a schema or select an existing schema or global schema that is previously added on the Components page, Schemas section. You can also add a sample for the schema that is added or selected. You can use these samples for API mocking. End users can use the samples to get a better understanding of the API.

• Method Responses

  You can define responses for different HTTP status codes. webMethods API Gateway gives you the flexibility to define responses for a status codes series.

  For example, you can define responses for status code series, such as the 2XX series or the 4XX series.

  For example, you can define specific response codes, such as 201 or 400.

  Note: If the response for a series and specific numbers in that series is defined, the more specific one is used. For example, if an entry for 2XX and 201 is added, a response with the HTTP status code 200 is the same as 2XX. However, a response with the HTTP status code 201 picks the one that is defined for 201.

  For each status code in a method response, you define the following parameters.

  • Response body. You define the response body that uses 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. End users can use the samples to get a better understanding of the API.
  • Header parameter. You can add a parameter to capture and process a header in the response that the native API sends.
  • Links. A developer of the native API can use links 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. Including links helps 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 specific place might also include links to methods that return the following information.
    • The temperature in centigrade.
    • The temperature of the place on a specific 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. Reuse the response that you define wherever you require by giving a reference.
• Method Callbacks

  A callback is an asynchronous API request that originates from the API server. This request 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 that is related to that event. API clients that are interested in an event or data that is related to that event, include a callback URL in the request they send to the API.

  To enable webMethods 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 webMethods API Gateway to process the initial requests, the callback URLs sent by clients, and the response sent by the API. Also, webMethods API Gateway processes the callback messages. Clients can provide the callback URL to webMethods API Gateway in any of the following ways:

  • Request header
  • Query parameter
  • Request body (if the response body has JSON or XML content)

  Define the relevant parameter to capture the callback URL to process it. webMethods 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, the webMethods API Gateway instance sends the requests that are 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 headers
  ${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 webMethods API Gateway is configured to process callback messages, webMethods API Gateway wraps the callback URL provided by the client and sends an webMethods API Gateway URL to the native API. When the native API invokes the same callback URL, webMethods API Gateway processes the response and applies the policies that are defined.

  webMethods API Gateway can apply the following policies on the callback messages:

  • 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.

Components

In the Components page, you can add reusable elements that you can use in other pages of the wizard. You can reference these global elements by using the $ref variable. You can add the following global elements.

• Schemas. The schema that is 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.
• Callbacks. You can define callback methods 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 and reuse them in methods. A request body includes the content type, a schema, and a sample.
• Responses. You can define responses and reuse them in methods. A response includes the content type, a schema, and a sample. It can also include header parameters and links.

API mocking

You can use the API mocking feature 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 you create the API and enable the API mocking function.

For more information about API mocking, see API mocking .

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.
• Links to download the API in the three different formats, Swagger, RAML, and OpenAPI.

In the Documentation page, in edit mode, you can add a file that contains any documentation that you want to include with the API. This file is accessible only from webMethods API Gateway.