

Importing APIs Via Dev First Approach¶

WSO2 API Controller (apictl) allows you to create and deploy APIs without using WSO2 API Publisher Portal. 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 API Manager environment.

Info

Before you begin

Make sure that the WSO2 API Manager CTL Tool is downloaded and initialized, if not, follow the steps in Download and Initialize the CTL Tool.
Make sure you already have added an environment using the CTL tool for the API Manager 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

The following is a sample API definition that can be used to generate an API Project.

Example

id:
 providerName: admin
 apiName: PizzaShackAPI
 version: 1.0.0
uuid: 8d87e646-f7c5-4dc2-9f45-64903ecccca4
description: This is a simple API for Pizza Shack online pizza delivery store.
type: HTTP
context: /pizzashack/1.0.0
contextTemplate: /pizzashack/{version}
tags:
- pizza
availableTiers:
- name: Unlimited
 displayName: Unlimited
 description: Allows unlimited requests
 requestsPerMin: 2147483647
 requestCount: 2147483647
 timeUnit: ms
 tierPlan: FREE
 stopOnQuotaReached: true
status: PUBLISHED
technicalOwner: John Doe
technicalOwnerEmail: [email protected]
businessOwner: Jane Roe
businessOwnerEmail: [email protected]
visibility: public
transports: http,https
corsConfiguration:
 accessControlAllowOrigins:
 - '*'
 accessControlAllowHeaders:
 - authorization
 - Access-Control-Allow-Origin
 - Content-Type
 - SOAPAction
 - apikey
 - testKey
 accessControlAllowMethods:
 - GET
 - PUT
 - POST
 - DELETE
 - PATCH
 - OPTIONS
productionUrl: http://localhost:8080
sandboxUrl: http://localhost:8081
endpointConfig: '{"endpoint_type":"http","sandbox_endpoints":{"url":"https:\/\/localhost:9443\/am\/sample\/pizzashack\/v1\/api\/"},"production_endpoints":{"url":"https:\/\/localhost:9443\/am\/sample\/pizzashack\/v1\/api\/"}}'
responseCache: Disabled
cacheTimeout: 300
implementation: ENDPOINT
authorizationHeader: Authorization
environments:
- Production and Sandbox
createdTime: "1599638524995"
environmentList:
- SANDBOX
- PRODUCTION
apiSecurity: oauth2,oauth_basic_auth_api_key_mandatory
accessControl: all
isLatest: true
enableStore: true
keyManagers:
- all

Response
```
Initializing a new WSO2 API Manager 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 WSO2 API Manager 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, the CTL Tool 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 WSO2 APIM 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
x-wso2-application-security	Specify application security (basic_auth, api_key, oauth2)	API level/ Resource 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_params.yaml
├── Docs
│    └── FileContents
├── Image
├── Meta-information
│    ├── api.yaml
│    └── swagger.yaml
├── README.md
└── Sequences
    ├── fault-sequence
    ├── in-sequence
    └── out-sequence

Sub Directory/File	Description
`api.yaml`	The specification of the created API.
`swagger.yaml`	The Swagger file that is generated when the API is created.
`api_params.yaml`	Contains environment-specific details.
`Sequences ├── fault-sequence ├── in-sequence └── out-sequence`	To add custom sequences, save them in XML format and add them to the corresponding folder. For example, to add a custom in-sequence, save the custom sequence as `SampleSequence.xml` and add it to the `Sequences/in-sequence/`directory.
`Docs \|── FileContents`	Contains the documents. To add a new document, add the document in the `Docs/FileContents/`directory.

Note

Changing the Default API Template

When you create an API Project, APIs are generated using the default template specified in <USER_HOME>/.wso2apictl/default_api.yaml file. Following is the default template used to generate API Projects.

id:
    providerName: admin
    version: 1.0.0
    apiName:
context:
type: HTTP
availableTiers:
    - name: Unlimited
status: CREATED
visibility: public
transports: http,https
productionUrl: http://localhost:8080
sandboxUrl: http://localhost:8081

This file contains the same notation as the <API-Project>/Meta-information/api.yaml. Organization-specific common API related details can be put into this template file and shared across developers.

To further finetune API creation, a custom API Definition file can be used. If you need to use a specific definition file when generating a certain API project, use the --definition or -d flag along with apictl init command. The custom definition file should be in YAML format only.

Generate APIs with Dynamic Data

When initializing an API Project, the CTL 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>/Meta-information/api.yaml file. You can edit the mandatory configurations listed below.

Field	Description
`apiName`	The name of API without spaces.
`context`	Context of the API in API Manager with a leading slash.
`productionUrl`	Production endpoint for API.
`sandboxUrl`	Sandbox endpoint for API.

For more information about the configurations, see the Sample_Api.yaml.

api.yaml

id:
    providerName: admin
    apiName: "SampleAPI"
    version: 1.0.0
type: HTTP
context: "/samplecontext"
availableTiers:
    - name: Unlimited
status: PUBLISHED
visibility: public
transports: http,https
productionUrl: http://localhost:8080
sandboxUrl: http://localhost:8081

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 admin role is 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> -k
```
```
apictl import-api --file <path to API Project> --environment <environment> -k
```
```
apictl import-api --file <path to API Project> --environment <environment> --params=<environment params file> -k
```
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 :
  --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 API Manager environment params file (The default file is api_params.yaml.).
  For more information, see Configuring Environment Specific Parameters.
  --skipCleanup : Leave all temporary files created in the CTL during import process. The default value is false.
Example
```
apictl import-api -f ~/myapi -e production -k
```
```
apictl import-api --file ~/myapi --environment production -k
```
```
apictl import-api --file ~/myapi --environment production --params prod/custom_api_params.yaml -k 
```
Tip

When using the --update flag with the import-api command, the CTL tool 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.
Response
```
Successfully imported API!
```

Top