Creating APIs in code view

Define and configure your APIs in IBM API Studio using YAML files in code view to edit complex configurations.

In the code view, you must create a YAML file with kind: API, specifying essential attributes such as metadata and specifications. This method ensures a structured and standardized API definition.

The kind field specifies the type of asset that is defined. When set to API, it indicates that the file represents an API configuration. This configuration includes metadata about the API, references to its specification, and associated policies.

Metadata section. Contains details such as the API’s name, namespace, version, and tags to help categorize and manage the API.
Specification reference. The api-spec field points to the API’s specification file, defining its structure and operations.
Policy sequence. The policy-sequence field lists the policies that are applied to the API. IBM API Studio enforces these policies in the defined execution order.

API configuration template

kind: API
apiVersion: api_version
metadata:
  name: api_name
  namespace: namespace
  version: version_number
  tags:
    - tag1
    - tag2
  type: API_type
spec:
  api-spec: 
    $path: path_to_api_spec
  policy-sequence: 
    - $ref: namespace:name:version

Each field in the template specifies important details that IBM API Studio uses to process and manage the API.

Category	Field	Description
	`kind`	Defines the type of asset. The value `API` indicates that the file represents an API configuration.
	`apiVersion`	Defines the version of the API schema being used.
`metadata`. Identifies and organizes the test with essential tags and identifiers.	`name`	Labels/Identifies the API. The name must be unique within the namespace.
	`namespace`	Defines the group label/identifier used to organize related policies. Namespaces are used to group related assets under a common category in order to organize the policies.
	`version`	Specifies the API version. Use this field to track changes and manage different versions.
	`tags`	Assigns keywords to the API. Tags help categorize and filter APIs based on specific attributes.
	`type`	Defines the API type. The supported type is `REST`. IBM API Studio processes the API based on this type.
`spec`. Defines the structure and behavior of the API. It includes essential configurations such as the API specification reference and policy sequence.	`api-spec`	Defines the API's structure, operations, and behavior by referencing an external file through the `api-spec` field. The specification follows OpenAPI (OAS) or Swagger standards and supports YAML and JSON formats, making the API easy to understand and use. The `$path` parameter specifies the location of the API specification file. The `api-spec` field forms the foundation of API behavior and documentation. It helps developers, tools, and consumers understand how the API works by specifying: Endpoints and methods. List API endpoints and supported HTTP methods (`GET`, `POST`, `PUT`, `DELETE`). Request and response structure. Define request payloads, query parameters, headers, and response formats. Authentication and security. Specify authentication methods like API keys, OAuth, or JWT. Data models. Describe request and response schemas to maintain consistency. Error handling. Document error responses and associated HTTP status codes.
	`policy-sequence`	Lists the policies applied to the API and enforces them in the defined order. Each policy is referenced by using the `$ref` parameter in the format `namespace:name:version`, where `namespace` groups related policies, `name` defines the policy, and `version` specifies the policy version.

A sample API configuration is as follows:

kind: API
apiVersion: api.ibm.com\v1
metadata:
  name: Payments
  namespace: API
  version: 1
  tags:
    - UPI 
  type: REST
spec:
  api-spec: 
    $path: petstore.yaml
  policy-sequence: 
    - $ref: policy:policyseq:1

The sample configuration defines an API named Payments in the API namespace. This API is categorized as a REST API and includes metadata such as version, tags, and type. The API specification is linked to an external YAML file (petstore.yaml), and policies are applied through a referenced policy sequence.