

Importing APIs Via Dev First Approach¶

ESB API Controller (apictl) allows you to create and deploy APIs without using the Publisher Portal of the MWARE ESB. You can use this feature to create an API from scratch or using an existing Swagger or Open API specification and then deploy it to the desired MWARE ESB environment.

Info

Before you begin

Make sure that the apictl is downloaded and initialized, if not, follow the steps in Download and Initialize the apictl.
Make sure you already have added an environment using the apictl for the MWARE ESB environment you plan to import the API to.

If not, follow the steps in Add an Environment.

Initialize an API project¶

Open a terminal window and navigate to the path you need to create the project.

You can follow either of the following ways to generate the project.

From Scratch

Command

apictl init <Project Path>

apictl init <Project Path> --definition <API definition template file>  --force=<force create project>

Example

apictl init SampleAPI

apictl init SampleAPI --definition definition.yaml --force=true

As an example, you can use the Sample-Api.yaml here to generate an API Project.

Response
```
Initializing a new MWARE ESB project in /home/user/work/SampleAPI
Project initialized
Open README file to learn more
```
Info

In this case, the project artifacts are generated according to a set of predefined templates. Therefore, after initializing the project, you need to go and edit the project artifacts manually.

From OpenAPI/Swagger Specification
You can use a Swagger2 and OpenAPI3 specification to generate an API. The file format should be YAML or JSON.

Command

apictl init <Project Path> --oas <Path to API specification>

apictl init <Project Path> --oas <Path to API specification> --definition <API definition template file> --force=<force create project>

Example

apictl init Petstore --oas petstore.yaml

apictl init Petstore --oas https://petstore.swagger.io/v2/swagger.json

apictl init Petstore --oas petstore.yaml --definition definition.yaml --force=true

Response
```
Initializing a new MWARE ESB project in /home/user/work/PetstoreAPI
Project initialized
Open README file to learn more
```
Info

When you initialize an API project using an OpenAPI specification, apictl will automatically read the OpenAPI definition and populate a certain set of configs in the API definition file, api.yaml.
Info

Flags:
- Optional :
  --definition or -d : Provide a YAML definition of API
  --oas : Provide an OpenAPI specification file/URL for the API
  --force or -f : To overwrite the directory and create the project

Note

You can define scopes for a resource when defining a Swagger2 or OpenAPI3 specification to generate an API.

Note

The following example is a template file. Please do the necessary changes to the template file before using this example to generate an API.

Example

openapi: 3.0.0
info:
title: Online-Store
version: v1.0.0
description: This API contains operations related to the online shopping store.
x-wso2-basePath: /store/{version}
x-wso2-production-endpoints:
urls:
    - http://products
paths:
/products:
    get:
    responses:
        "200":
        description: successful operation
/products/{productId}:
    get:
    parameters:
        - name: productId
        in: path
        required: true
        schema:
            type: string
    security: 
        - 
        default: 
            - "read"
    responses:
        "200":
        description: successful operation
components: 
securitySchemes: 
    default: 
        type: "oauth2"
        flows: 
            implicit: 
            authorizationUrl: "https://test.com"
            scopes: 
                read: ""
            x-scopes-bindings: 
                read: "admin"

First you need to define the scope name ("read") under security > default section inside the required resource and then define the role binding under the securitySchemes section. You can use any preferred name as the security scheme.

Make sure to set the security type as oauth2 when defining the scopes. Also when defining the roles under a particular scope, put them under x-scopes-bindings: as a scope name and roles mapping.

Note

You can define MWARE ESB supported open API extensions for an API when defining a Swagger2 or OpenAPI3 specification to generate an API. These extensions can be used to define endpoint configurations, runtime configurations, resource level throttling, and API level throttling, transport-level security, CORS configurations and response cache configurations. The list of APIM supported OpenAPI extensions is as follows.

Extension	Description	API Level/ Resource Level
x-wso2-basePath	The base path which gateway exposes the API	API level
x-wso2-production-endpoints	Specify the actual back end of the service	API level
x-wso2-sandbox-endpoints	Specify the sandbox endpoint of the service if available	API level
x-wso2-throttling-tier	Specify the rate-limiting for the API or resource	API level/ Resource level
x-wso2-cors	Specify CORS configuration for the API	API level
x-wso2-disable-security	When the value of this extension specified as true, the resources can be invoked without any authentication	API level/ Resource level
x-wso2-response-cache	Enable response caching when creating a new API with cache timeout	API level
x-wso2-mutual-ssl	Enable mutual SSL for API (With optional and mandatory keywords as values)	API level
x-wso2-auth-header	Specify the authorization header for the API in which either bearer or basic token is sent	API level
x-wso2-transports	Specify the transport security for the API (HTTP, HTTPS, and Mutual SSL)	API level

Let's see how these OpenAPI extensions are used in Open API definition.

A project folder with the following default structure will be created in the given directory.

├── api.yaml
├── api_meta.yaml
├── deployment_environments.yaml
├── Client-certificates
├── Definitions
│   └── swagger.yaml
├── Docs
├── Endpoint-certificates
├── Image
└── Policies

Sub Directory/File	Description
`api.yaml`	The specification of the created API.
`api_meta.yaml`	The meta-information file of the source artifact (This includes the name and the version of the API).
`deployment_environments.yaml`	Specify the gateway environments to which the API should be deployed.
`swagger.yaml`	The Swagger file that is generated when the API is created.
Policies	Contains the operation policies attached to the operations of the API. To learn more about adding a custom operation policy with dynamic data, see Add dynamic data to Operation Policies in an API project.
Client-certificates	Contains the client certificates for Mutual SSL enabled APIs.
Docs	Contains the documents.
Endpoint-certificates	Contains the endpoint certificates for endpoint security enabled APIs.
Image	Contains the thumbnail image of the API.

Note

Overriding an API with organization-specific details and further finetuning

When you create an API Project, APIs are generated using a default template. To further finetune the process of creating the API and to include organization-specific common API related details, you can use a custom API Definition file. For more information, see Initialize an API project.

Generate APIs with Dynamic Data

When initializing an API Project, apictl is capable of detecting environment variables in the default definition file or in the provided custom definition file. For more information on using dynamic data, see Initialize API Projects with Dynamic Data.

Open the <API Project>/api.yaml file. You can edit the mandatory configurations in the field named data as listed below.

Field	Description
`name`	The name of API without spaces.
`context`	Context of the API in MWARE ESB with a leading slash.
`production_endpoints`	Production endpoints for API.
`sandbox_endpoints`	Sandbox endpoint for API.

For more information about the configurations, see the Sample-Api.yaml.

api.yaml

    type: api
    version: v4.2.0
    data:
        name : SampleAPI
        version: 1.0.0
        context: /sampleapi
        endpointConfig:
            endpoint_type: http
            production_endpoints:
                url: http://prod.wso2.com
            sandbox_endpoints:
                url: http://sand.wso2.com
        endpointImplementationType: ENDPOINT
        lifeCycleStatus: CREATED
        policies:
        - Unlimited
        provider: admin
        transport:
        - http
        - https
        type: HTTP
        visibility: PUBLIC

Import an API project¶

Info

Before you begin...

Make sure you have already created an environment to which you are planning to import the API. If not, follow steps in Add an Environment.
Make sure you have logged-in to the importing environment. If not, follow steps in Login to an Environment.

Tip

A user with Internal/devops role or admin role are allowed to import APIs. To create a custom user who can import APIs, refer Steps to Create a Custom User who can Perform API Controller Operations.

After editing the mandatory fields in the API Project, you can import the API to an environment using any of the following commands.

Command
```
apictl import api -f <path to API Project> -e <environment> 
```
```
apictl import api --file <path to API Project> --environment <environment> --rotate-revision
```
```
apictl import api --file <path to API Project> --environment <environment> --params=<environment params file> 
```
Info

Flags:
- Required :
  --file or -f : The file path of the API project to import.
  --environment or -e : Environment to which the API should be imported.
- Optional :
  --rotate-revision : If the maximum revision limit reached, delete the oldest revision and create a new revision.
  --skip-deployments : Skip the deployment environments specified in the project and only update the current API of the API.
  --preserve-provider : Preserve the existing provider of API after importing. The default value is true.
  --update : Update an existing API or create a new API in the importing environment.
  --params : Provide a ESB environment params file. For more information, see Configuring Environment Specific Parameters.
  --skip-cleanup : Leave all temporary files created in apictl during import process. The default value is false.
Note

Importing versions of an API
```
-   When importing versions of an API, you are not allowed to change the API provider. 
-   If the preserve-provider value was set to `true` when importing the initial API, the value should be set to `true` when importing all its' versions.
-   If the preserve-provider value was set to `false` when importing the initial API, the value should be set to `false` when importing all its' versions.
```
Example
```
apictl import api -f ~/myapi -e production 
```
```
apictl import api --file ~/myapi --environment production --rotate-revision
```
```
apictl import api --file ~/myapi --environment production --params prod/params.yaml  
```
Tip

When using the --update flag with the import api command, apictl will check if the given API exists in the targeted environment. If the API exists, it will update the existing API. If not, it will create a new API in the imported environment.
Note

Changes to the import command with the revision support for APIs
- From MWARE ESB 4.0.0 onwards, you have to create a new revision in order to deploy an API in a Gateway environment and only a revision can be deployed in a Gateway environment.
- With the import command of the apictl, if the API project has specified the deployment environments, the import will first update the current API of the API.
- If the number of revisions created for that API do not exceed the max revision limit of 5, a new revision of that API will be created and that revision will be deployed in the specified Gateway environments.
- If the max revision numbers are reached, the imported API will only update the current API and not be deployed in the specified Gateway environments.
- You can use the --rotate-revision flag with the import command and if the max revision limit is reached, the import operation will delete the earliest revision for that API and create a new revision. This new revision will be deployed in the specified Gateway environments.
Note

apictl import-api command has been deprecated from apictl 4.0.0 onwards. Instead use apictl import api as shown above.
Response
```
Successfully imported API!
```

Top