Creating an API from scratch

Edit online

About this task

Creating an API from scratch involves several key steps, from defining its general structure to securing and documenting it. The Create API wizard streamlines this process by guiding you through logical steps to make sure a well-structured and maintainable API.

The following sections outline the key sections in the API creation process:

  • General information. Defines the API’s purpose, versioning strategy, and supported formats for consistency and maintainability.
  • Paths & Operations. Lists API endpoints and HTTP methods for effective resource interaction.
  • Security. Configure authentication, authorization controls, and data protection strategies to safeguard API access.
  • Components. Introduce reusable elements such as request or response schemas, headers, and error-handling formats.
  • Documentation. Provide a link to the API documentation.
  • API mocking. Simulate API responses for development and testing, enabling faster iteration and debugging.
  • Scopes. Define fine-grained access controls to make sure that API consumers have the appropriate permissions for different operations.
  • Policies. Define and enforce rules that govern API behavior, security, and performance.
General information

The General information page includes fields to identify, categorize, and group an API. It also includes fields to define one or more server URLs and add variables to the API.

Paths and operations

The Paths and operations page lets you define API resources and their associated HTTP methods.

Defining resources

Each resource requires the following properties:

  • Name. The resource name.
  • Summary. A brief overview of the resource.
  • Description. A detailed explanation of its purpose.
  • Supported operations. HTTP methods. For example, GET, POST, PUT, DELETE.
  • Parameters. Define query, strings, or path parameters that are required in API requests.

Each method requires the following properties:

  • Operation ID. A unique identifier.
  • Tags. Labels for organizing and categorizing methods.
  • Parameters. Define query, header, or path parameters for handling request data.

Method requests

In the Request body section, define the schema for requests that contain JSON or XML payloads. Since a method can support multiple content types, you must:

  1. Add a content type.
  2. Define the schema for that content type.

You can enter a schema manually or select an existing schema from the Components page. You can also add sample data for API mocking and reference.

Method responses

Define responses for different HTTP status codes. You can specify responses for status code series (such as 2XX or 4XX) or specific codes (201, 400).

You can define responses for different HTTP status codes. You can specify responses for a status code series (such as 2XX or 4XX) or for specific codes like 201 or 400.

Response structure for each status code, provide:

  • Response body. You define the response body by 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.
    • Example. You can add a sample response for API mocking.
  • Header parameter. You can add a parameter to capture and process a header in the response that the native API sends.
  • Links. Define relationships between responses and other API operations. You can include links to related methods in the response, allowing an API client to dynamically go to the available methods. For example, a method that returns the temperature in Fahrenheit for a location can include links to methods that provide:
    • The temperature in Celsius.
    • The temperature for the location on a specific day of the year.
Note: When both a status code series and a specific code within that series are defined, the more specific response takes precedence.

For example:

If you define responses for 2XX and 201:

  • A 2XX response applies to all 2XX codes.
  • A 201 response overrides 2XX for status 201.
API mocking
API mocking simulates an API’s behavior by creating a mock server or mock responses. You can use this approach to test and integrate applications without relying on a real API, which can be slow, unavailable, or under development.
Components

On the Components page, you can add reusable elements for use in other pages of the wizard.

Procedure

  1. From the home page, select an existing project. If no project exists, create a new project.
    The project opens in the Development tab.
  2. In the quick access page, click Add an API > Create.
    The Create API page is displayed.
  3. On the Create API page, provide the API details.
    • API name. Provide a name for the API. For example, Pet Store.
    • Namespace. Define a domain for the API to avoid conflicts with other APIs.
    • API version. Specify the version of the API to manage changes over time. The default value is 1.0.
    • API type. The API type is set to REST by default. Only REST APIs are supported.
    • Maturity state. Indicate the API's development stage, such as Draft, Published, or Deprecated.
    • API grouping. Organize related APIs under a common group for better management.
    • Tags. Add labels to categorize the API for improved search and filtering.
  4. Click Create.
    The following files are generated:
    • An API file with kind: api. For example, Pet Store.yaml.
    • An API specification file. For example, Pet Store-spec.yaml.
  5. Select the API file that is generated.
  6. Select General information from the Outline section and provide the API details.

    General information includes the key details about the API, including its purpose, versioning, contact information, license, and server details.

    • Title. The name of the API. For example, Pet Store.
    • Summary. A short overview of the API’s purpose.
    • Version. The version of the OpenAPI document and not the API itself.
    • Description. A detailed explanation of the API’s functions.
    • Terms of Service . A URL linking to the API’s terms of service.
    • Contact. Provides support information for the API. This information includes contact name, contact URL, and email.
    • License. Defines the license for API usage. This information includes:
      • License name. Official name of the license. For example, Apache 2.0, MIT.
      • License identifier. An SPDX identifier for standardized licenses.
      • License URL. A link to the full license details.
    • Server. Specifies one or more server URLs where the API is hosted. Click Add server and provide the Server URL.
  7. Select Path & Operations from the Outline section.
    1. Click Add path and provide the path details:
      • Name. Enter the name of the path, which represents the endpoint. For example, /pet.
      • Summary. Provide a brief summary of what the endpoint does.
      • Description. Add a detailed explanation of the endpoint's purpose and behavior.
      • Supported operations. Select the applicable HTTP methods for the endpoint. The available options are GET, PUT, POST, DELETE, PATCH, and HEAD.
    2. Click Save.
    3. Click the path that you created.
    4. In the Path parameters section, click Add parameter > Add a new parameter to add the API-level parameters. You can also select Refer to components to reuse parameters defined on the Components page.
    5. On the Add parameter page, provide the parameter details.
      • Parameter name. Name of the parameter.
      • Located in. Select the parameter location. Available values: query, header, path, cookie.
      • Description. Brief description of the parameter.
      • Select any of the following parameter attributes based on your preference:
        • Explode. Specifies how to serialize array or object parameters in requests. Selecting the checkbox serializes each item separately.
        • Deprecated. Marks the parameter as deprecated. The parameter remains functional but is not intended for use. It is planned for removal in future versions.
        • AllowEmptyValue. Specifies whether a query parameter can be included without a value.
      • Click Next.
      • Add the content type and schema or only the schema and click Next.
      • Add examples, and click Add.
    6. Click Add server to add the API servers.
    7. On the Add server page, provide the Server URL and Description.
    8. Click Add variable and provide the variable details.
      • Name
      • Description
      • Default
      • Enums
    9. Click Save to add the variable.
    10. Click Save to add the server.
    11. For each supported method added for a resource, provide the method details.
      • Operation ID. Unique identifier for the operation.
      • Tags. Keywords associated with the operation for categorization.
      • Summary. Brief summary of the operation's purpose.
      • Description. Detailed explanation of the operation, including its functions and use case.
      • Operation parameters. Defines the input parameters for the operation, such as query, header, path, or cookie parameters. You can add new parameters or select the existing parameters that are defined in the Parameters section on the Components page.
      • Request body. Specifies the structure and content of the request payload, if applicable.
      • Content types. Lists the supported media types for request and response payloads, such as application/json or application/xml.
      • Responses. Defines the expected responses, including status codes and response body structures. You can select an existing response that is defined in the Responses section on the Components page.
      • Security. Specifies authentication and authorization requirements for accessing the operation.
      • Server. Defines the server or endpoint where the operation is available.
  8. Select Security from the Outline section. Click Add security scheme and choose a security scheme from the list. The list includes security schemes that are defined in the Security schemes section on the Components page.
  9. Select Components from the Outline section and add the global elements.
    • Schemas. The schema that is specified here can be reused in the paths and operations specifications across multiple methods and resources.
    • Responses. You can define responses in here and reuse them in methods. A response includes the content type, a schema, and an example. It can also include header parameters and links.
    • Parameters. You can define parameters that can be used as API, resource, and method parameters.
    • Examples. You can add examples that can be reused as samples across operations in the API.
    • Request bodies. You can define request bodies here and reuse them in methods. A request body includes the content type, a schema, and an example.
    • Headers. You can define parameters that can be reused as header parameters at the API, method, and response levels.
    • Security schemes. You can define multiple security schemes to control access and authenticate API consumers. These schemes define how clients must present credentials when they send API requests. Each security scheme offers different levels of protection based on the API’s requirements.
    • Links. You can define links that can be reused in responses.
  10. Select Documentation from the Outline section. Click Add documentation.
    1. Provide the documentation URL and Description.
    2. Click Add.
  11. Select API mocking from the Outline section. Click Configure mocking to set up and customize the mocking behavior for the API. For more information, see Mocking APIs.
  12. Select Scopes from the Outline section. Click Add scope and provide the following information:
    1. Name. Unique identifier for the scope.
    2. Namespace. Logical grouping for organizing scopes.
    3. Version. Version number to track scope changes.
    4. Description. Explanation of the scope’s purpose.
    5. Click Save to create the scope.
    6. Click the newly created scope to view its details.
    7. The scope includes a collection of REST resources and methods that are associated with it.
    8. Select the wanted methods for the available paths to define access control.
    The API is successfully created and available for further configuration.
  13. Select Policies from the Outline section. Click Add policy sequence and provide the following information:
    1. Policy name. Unique identifier for the scope.
    2. Namespace. Logical grouping for organizing policies.
    3. Version. Version number to track policy changes.
    4. Tags. Keywords associated with the policy for categorization.
    5. Click Create to create the policy.
    6. In the Policy configuration section, select the required policy from the List of policies.
    7. On selecting a policy, you can do one of the following:
      • Add a new policy. Click Add a new policy and provide the required policy details.
      • Refer exisiting policy. Click Refer exisiting policy and select one of the previously defined policies.
      The chosen policies are listed in the Selected policies section.
    8. From the Selected policies section, click on the policy link created.
      The policy form view for the selected policy appears.
    9. Specify the required details in the policy form view.
      For more information about the available Form view field configurations in the supported policies, refer Supported policies.

What to do next

You can define policies to enforce security, traffic management, and transformations. Configure the required policies, deploy the API, and run tests to validate its behavior.