Creating a REST API

Edit online

You can create a REST API from scratch by providing the basic information, technical information and defining the resources and methods you require.

About this task

You must have the Manage APIs or activate/deactivate APIs functional privilege to perform this task.

Procedure

  1. Open the menu options and select APIs.
    A list of all existing APIs appears.
  2. Click Create API.
  3. Select Create from scratch.
  4. Select REST.
  5. Click Create.
    The Basic information page of the Create REST API wizard appears.
  6. Provide the information in the Basic information section as follows.
    Field Description
    Name Name of the API.
    Version Version of the API.
    Maturity state Maturity state of the API. Available values are, Beta, Deprecated, Experimental, Production, Test.

    The available values depend on the Maturity states that are configured in the apiMaturityStatePossibleValues property under Administration > Extended settings section.
    API grouping Group under which the API can be categorized. Available values are, Finance Banking and Insurance, Sales and Ordering, Search and Transportation and Warehousing.

    The available values depend on the groups that are configured in the apiGroupingPossibleValues property under Administration > Extended settings section.
    Tags Keywords for categorizing, identifying and organizing APIs. You select from the list of existing tags or create new tags.
    Description Description of the API.
  7. Click Continue to provide technical information for this API.
    Note: Click Save to save the API at this stage and close the Create REST API wizard.
  8. Provide the details of the servers that serve the API in the Add server details section.
    1. Click Add server and provide a Server URL and Description. You can include variables in the server URL by enclosing them in curly braces. These variables are added to the list of variables. However, you must edit these variables to add a default value. You can add one or more values and a description.
    2. Click Add variables and provide the information for the Name, Description, Default, and Value fields.
    Note: Click + to add the value that you create. Click Add to add the variable.
  9. Click Add Parameter and provide the information to add the API-level parameters as follows.
    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type. Available values, Query-string, Header, Cookie.
    Data type Specifies the data type. Available values, String, Date, Date time, Integer, Double, Boolean, File.
    Required Select the option if you require the parameter.
    Repeat Select the option if the input parameter is of type array.
    Value Specifies the possible values.
    Note: Define parameters only for the data that you want webMethods API Gateway to process.
  10. Type a Service registry display name.
    By default, the API is displayed in service registries with the name, APIName_Version. If you want the API to appear in the service registries with a different name, you can type the name here.
  11. Click Continue to provide Resource and methods for this API.
    Note: Click Save to save the API at this stage and close the Create REST API wizard
  12. Add resources to the API in the Resources and methods page.
    1. Click Add Resources and provide the following information.
      Field Description
      Resource name Name of the resource. The name that you provide is the display name of the resource and resource path that is used for execution.
      Resource path Specifies the path of the resource. The resource path must contain a "/".
      Description Description of the resource.
      Supported methods Select the methods that the API supports. Available values, GET, HEAD, POST, PUT, DELETE, PATCH.
    2. Click Add. The resource is added. You can add multiple resources.
    3. Add Tags.
    4. Click Add Resource Parameter and provide the information as follows.
      Field Description
      Name Name of the parameter.
      Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the list.
      Description Brief description of the parameter.
      Type Specifies the parameter type. Available values, Path, Header, Query-string, Cookie.
      Data type Specifies the data type. Available values, String, Date, Date time, Integer, Double, Boolean, File.
      Required Select the option if you require the parameter.
      Repeat Select the option if the input parameter is of type array.
      Value Specifies the possible values for the parameter.
    5. Click + Add to add the resource parameter.
  13. For each supported method that is added for a resource, provided the information as follows.
    1. Common information
      Field Description
      Description Type a description for the operation.
      OperationId Type an operation ID.
      Tags Type or select the keywords that you want to add to the operation.
    2. Method parameters
      Field Description
      Name Name of the parameter.
      Reference If you want to reuse a global parameter that is defined on the Components page, select the parameter from the list.
      Description Brief description of the parameter.
      Type Specifies the parameter type. Available values, Query-string, Header, Cookie.
      Data type Specifies the data type. Available values, String, Date, Date time, Integer, Double, Boolean, File.
      Required Select the option if you require the parameter.
      Repeat Select the option if the input parameter is of type array.
      Value Specifies the possible values for the parameter.
    3. Requests. You can select an existing global request that is defined on the Components page or specify a new request.
      To type a new request, select New request and provide the following information.

      • Content type. Select one and click Add.

      • Schema. Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After you create the global schema, you can select it from the Select a Schema list.

      • Sample.Type a sample for selected schema. Use this sample for API mocking.

    4. To use an existing global request to process a request, select Global request and provide the following information.

      • Name

      • Reference. Select one and click Add.

    5. Responses. First, add a status code from the Status Code list.
      Click the status code to select it. For the status code, you can select an existing global response that is defined on the Components page or provide a new response. To provide a new response, select New response and define the response by adding a schema and a sample for the response body, header parameters, and links.
      Note: You can also define the response for an HTTP status code series, such as 2 or 4.

      To define a new response for the selected status code, click Add response + and provide the information as follows.

      • Content type. Select one of the available content types and click Add.
      • Schema. Type a schema in the text box or select an existing schema from the Select a Schema list.

        You can also click Add global schema and create a new global schema on the Components page. After you create the global schema, you can select it from the Select a Schema list.

      • Sample. Type a sample for selected schema. This sample can be used for API mocking.

      To use an existing global response, select Global response and provide the following information:

      • Name. Name of the response.
      • Reference. Select one and click Add.

      To add a header parameter, click + Add header parameter and provide the following information to add a header parameter:

      • Name. Name of the parameter.
      • Reference. If you want to reuse a global parameter defined on the Components page, select the parameter from the list.
      • Description. Brief description of the parameter.
      • Type. Specifies the parameter type. Available values, Header.
      • Data type. Specifies the data type. Available values are, String, Date, Date time, Integer, Double, Boolean, File.
      • Required. Select the option if you require the parameter.
      • Repeat. Select the option if the input parameter is of type array.
      • Value. Specifies the possible values for the parameter.

      Click + in the Value text box to add a value to the list, and click Add to add the header.

      To add a link, click + Add links and provide the following information to add a link.

      • Name. Name of the link
      • Description. Description for the link.
      • Link. You can add a link or select an existing global link that is defined on the Components page.

      To add a link, select New link and provide the following information.

      • Type. Select OperationId for local operations. You can use OperationRef for both local and external operations.
      • Value. If Type is OperationRef, provide a reference to the target operation using the JSON Reference syntax \(using by the $ref keyword\). If the Type is OperationId, provide the Operation ID of the target operation.
      • Parameters. Specify the parameters of the target operation that you require to follow the link. Provide a Name and Value, and click Add.
      • Request body. Provide a request body only if the target operation has a body. Define the contents of the body of the target operation.

      To include an existing global link, select Global link and then select an existing global link from the Reference list.

    6. Callbacks. You can add the callbacks that the method supports. You can add new callbacks and select existing global callbacks.
      To specify a new callback, click + Add callbacks and define the callback:
      • Name. A name for the callback resource.
      • Click + Add resources and provide details of the API that serves as the callback API.
      Note: The user interface and procedure for defining a callback is similar to defining a resource and methods within the resource.

      To include a global callback defined on the Components page, provide the following information.

      • Name. Name of the callback resource.
      • Reference. If you want to reuse a global callback defined on the Components page, select the callback from the list and click Add.
  14. Click Continue to provide Mocking information for this API .
    Note: Click Save to save the API at this stage and close the Create REST API wizard. The API mocking page appears. API mocking is not enabled for a new API. Edit the API and enable API mocking after you create the API.
  15. Click Continue to define API components for this API. Alternatively, you can click Components.
    Note: Click Save to save the API at this stage and close the Create REST API wizard
  16. Define the reusable elements that you want to reuse in other pages of the Create REST API wizard. An API might have several elements that are common across resources and methods, such as schemas for response bodies. You can place such common elements in the Components section and reference them using the $ref alias.
    1. In the Schemas section, click + Add schema and provide the following information.
      Field Description
      Name Name of the schema.
      Schema type Specifies the schema type. Available types are, Inline schema and External schema.
      Value Specifies the value for the schema type you select.

      For an inline schema, type the request and response values.

      For an external schema, click Browse to upload a schema.

      Click + Add to add the schema component.

    2. In the Parameters section, click + Add parameter and provide the following information.
      Field Description
      Name Name of the parameter.
      Description Description of the parameter.
      Type Specifies the parameter type. Available values are, Path, Query-string, Header and Cookie.
      Data type Specifies the data type. Available values are, String, Date, Date time, Integer, Double, Boolean, and File.
      Required Select the option if you require the parameter.
      Repeat Select the option if the input parameter is of type array.
      Value Specifies the possible values for the parameter.

      Click + Add to add the parameter component.

    3. In the Headers section, click + Add header and provide the following information.
      Field Description
      Name Name of the header.
      Description Description of the header.
      Type Specifies the header type. The value is fixed as Header for headers.
      Data type Specifies the data type. Available values are, String, Date, Date time, Integer, Double, Boolean, and File.
      Required Select the option if you require the header.
      Repeat Select the option if the input parameter is of type array.
      Value Specifies the possible values for the header.

      Click + Add to add the header component.

    4. In the Examples section, click + Add examples and provide the following information.
      Field Description
      Name Name of the example.
      Summary Description of the example.
      Value The content of the example.

      Click + Add to add the example component.

    5. In the Links section, click + Add links and provide the following information.
      Field Description
      Name Name of the link.
      Description Description of the link.
      Type Specifies the link type. Available values are, OperationiD, OperationRef.
      Value Specifies a path to the target operation or a reference to the target operation.
      Parameter name Specifies the name of the parameter that is passed as a parameter to the target operation.
      Parameter value Value for the parameter. Click + Add to add the parameter. You can add more parameters.
      Request body Payload of the request sent to the target operation.

      Click Add to add the link component.

    6. In the Callbacks section, click + Add callback and provide the following information.
      • Type a name for the callback.
      • Click + Add resources.
      • Type the Callback path.
      • Select the supported methods.
      • Click Add.
      • For each method that you add, complete the next two steps.
      • Click + Add Resource Parameter and add the resource parameters that you require. The procedure for adding resource parameters is given in Step 11d.
      • Define the selected methods. The procedure for defining methods is given in Step 12.
    7. In the Request Bodies section, click + Add request and provide the following information.
      Field Description
      Name Name of the request.
      Content type Select a content type from the list.
      Schema You can also select an existing schema.
      Sample Type a sample of the schema.

      Click Add to add the request component.

    8. In the Responses section, click + Add Response and provide the following information.
      Field Description
      Name Name of the response.
      Content type Click Add to add a content type.
      Schema You can also select an existing schema.
      Sample Type a sample of the schema.
      Header Parameter Click + Add Header Parameter and provide the information that you require. Then, click + Add to add the header parameter.
      Links Click + Add Links and provide the information that you require. Then, click Add to add the link.

      Click Add to add the response component.

  17. Click Continue to provide API documents for this API >.
    The Documentation page appears.
    Note: Click Save to save the API at this stage and close the Create REST API wizard.
  18. Type a display name and click Browse to select a file.
  19. Click + Add to upload the file and add a row.
  20. Click Save to save your changes and create the API.