Creating APIs from scratch

Build a structured, secure, and well-documented API by defining resources, operations, security, and reusable components.

1. From the home page, select an existing project. If no project exists, create a new project.
2. In the Quick start 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.
   • 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.
     Note: You can view the specification file only in code view.
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.
   • 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 Add.
   3. Click the path 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, enter the variable details, and then click Save.
   9. Click Save to add the server.
   10. 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 Tags from the Outline sections and enter the tag details. Click Save.
10. 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.
11. Select Documentation from the Outline section. Click Add documentation.
    1. Provide the documentation URL and Description.
    2. Click Add.
12. 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.
13. 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.
14. Select Policy sequence from the Outline section and add policies. For more information, see Creating a policy sequence.
15. Select the URI schemes from the Outline section and add the required details.
16. Select the CORS from the Outline section and add the required details.
17. Select the Properties from the Outline section and add the required details.