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: 852464c8-a53a-45f9-9ef1-0e532fbd0767 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 documents: [] lastUpdated: Dec 21, 2020 11:00:28 AM availableTiers: - name: Unlimited displayName: Unlimited description: Allows unlimited requests requestsPerMin: 2147483647 requestCount: 2147483647 unitTime: 0 timeUnit: ms tierPlan: FREE stopOnQuotaReached: true availableSubscriptionLevelPolicies: [] uriTemplates: [] apiHeaderChanged: false apiResourcePatternsChanged: false status: PUBLISHED technicalOwner: John Doe technicalOwnerEmail: [email protected] businessOwner: Jane Roe businessOwnerEmail: [email protected] visibility: public gatewayLabels: [] endpointSecured: false endpointAuthDigest: false transports: http,https advertiseOnly: false apiOwner: admin subscriptionAvailability: all_tenants corsConfiguration: corsConfigurationEnabled: false accessControlAllowOrigins: - '*' accessControlAllowCredentials: false accessControlAllowHeaders: - authorization - Access-Control-Allow-Origin - Content-Type - SOAPAction - apikey accessControlAllowMethods: - GET - PUT - POST - DELETE - PATCH - OPTIONS 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 scopes: [] isDefaultVersion: false isPublishedDefaultVersion: false environments: - Production and Sandbox createdTime: "1608528625313" additionalProperties: {} monetizationProperties: {} isMonetizationEnabled: false environmentList: - SANDBOX - PRODUCTION apiSecurity: oauth2,oauth_basic_auth_api_key_mandatory endpoints: [] enableSchemaValidation: false apiCategories: [] accessControl: all rating: 0.0 isLatest: true
-
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. 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: - "products:read" responses: "200": description: successful operation components: securitySchemes: 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 thesecuritySchemes
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, and API level throttling, transport-level security, and CORS configurations and response cache configurations. The list of APIM supported open API extensions are as follows.
Extension
Description
API Level/ Resource Level
x-wso2-basePath
The base path on which the 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
- Optional :
-
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 theSequences/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 withapictl 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 istrue
.--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 isapi_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 isfalse
.
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 theimport-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. - Required :
-
Response
Successfully imported API!