Serverless-wso2-apim NPM

serverless-wso2-apim

Serverless Framework plugin to manage APIs on WSO2 API Manager.

Compatible with

Features

Create, Update and Publish your API definitions via sls deploy.
Manage your API definitions via sls info and sls remove.
Supports HTTP and JMS backends with mediation policies & additional API properties.
Uploads backend certificates (including CAs) to enable HTTP/s connectivity with backends.
Supports Swagger 2.0 and OpenAPI 3.0 specifications and will publish them to WSO2 Store / Dev Portal.
Automatically detects the version of WSO2 API Manager running.

Install Plugin

Discover it on npmjs.com @ here
yarn add -D serverless-wso2-apim or npm install --save serverless-wso2-apim
Then in serverless.yml add following entry to the plugins array:
```
plugins:
  - serverless-wso2-apim
```

Using the Plugin

Make sure you have a Serverless project set up as described here.

Add configuration options to your Serverless configuration, as below.

custom:
  wso2apim:
    enabled: true
    host: "wso2-apimanager.com"
    port: 443
    user: "user@tenant"
    pass: "password"
    gatewayEnv: "Production and Sandbox"

Add one or more API definitions to your Serverless configuration, as below.

serverless.yml:

custom:
  wso2apim:
    apidefs:
      - myAwesomeAPI: # Your API Definition Identifier
        name: "MyAwesomeAPI" # (CANNOT BE UPDATED LATER) Your API Name
        version: "v1" # (CANNOT BE UPDATED LATER) Your API Version, which also forms a part of the API URL ultimately
        rootContext: "/myawesomeapi" # (CANNOT BE UPDATED LATER) Your API Context, which will be exposed by WSO2 API Gateway. Must be unique per Gateway Environment.
        description: "My Awesome API"
        visibility: "PUBLIC"
        backend:
          http: # HTTP-based Backends
            baseUrl: "https://backend:port/123"
            certChain: "file://certs/backend.cer"
        mediationPolicies: # Optional
          in: "log_in_message"
          out: "None"
          fault: "None"
        apiProperties: # Optional
          "property1": "value1"
          "property2": "value2"
        maxTps: 100
        tags:
          - my-awesome-api
          - awesomeness
        swaggerSpec: # Swagger 2.0 / OpenAPI 3.0 specification in YML

Run sls deploy to create-and-publish (or) update-and-republish API definitions (and associated backend certificates, if supplied) in WSO2 API Manager.
Run sls info to view the status of API deployment on WSO2 API Manager.
Run sls remove to delete API definitions (and associated backend certificates, if exists) when there are no active subscriptions exist on those APIs.

Configuration Reference

custom.wso2apim.*
Parameter What? Usage Example
enabled Default is true. When set to false explicitly, deployment of APIs on WSO2 will be skipped. Suitable for offline testing etc. true
host WSO2 API Manager Hostname wso2-apimanager.com
port WSO2 API Manager Port 443
user Username with an optional tenant symbol. user@tenant
pass Password, supports Serverless Variables syntax. xxx
gatewayEnv Target gateway environment, as configured in your WSO2 installation. Production and Sandbox
custom.wso2apim.apidefs.<Your-API>.*
Parameter What? Usage Example
name (CANNOT BE UPDATED LATER) Your API Name MyAwesomeAPI
version (CANNOT BE UPDATED LATER) Your API Version, which also forms a part of the API URL ultimately. v1
rootContext (CANNOT BE UPDATED LATER) Your API Context, which will be exposed by WSO2 API Gateway. Must be unique per Gateway Environment. /myawesomeapi
description Free-form text My Awesome API
visibility Supports PUBLIC (Visible to everyone) and PRIVATE (Visible to current tenant). Kept in the api for backwards compatibility. Please use fields for subscriberVisibility and publisherVisibility. PUBLIC
subscriberVisibility Visibility of the API in the developer portal. Supports PUBLIC (Visible to everyone) and PRIVATE (Visible to current tenant) and RESTRICTED (Visible to it's tenant domain and only to the user roles that you specify. You should provide the roles in the subscriberVisibilityRoles.). RESTRICTED
subscriberVisibilityRoles The user roles that are able to access the API in Store. Only applicable in combination with subscriberVisibility. admin
publisherVisibility Visibility of the API in the publisher portal. Supports PRIVATE (Visible to all logged in publishers/creators) and RESTRICTED (Visible to logged in publishers/creators with the roles that you specify. You should provide the roles in the publisherVisibilityRoles.). RESTRICTED
publisherVisibilityRoles The user roles that are able to access the API in Store. Only applicable in combination with publisherVisibility. admin
backend Supports http and jms backends. Note: One API definition supports only one backend.
backend.http.baseUrl Your HTTP backend base URL. It supports: a. URL - Any valid HTTP URL. b. AWS CloudFormation Export - Exported value must contain a valid HTTP URL. This value is only being used for the Production Endpoint, the Sandbox Endpoint is not supported anymore https://backend:port/123 (or) !ImportValue xx
backend.http.certChain Optional, your backend certificate chain in PEM (base64) format. It supports: a. File system - Path must be relative to where serverless.yml is located. b. AWS Certificate ARN c. AWS CloudFormation Export - Exported value must contain a valid AWS Certificate ARN. file://certs/backend.cer (or) arn:aws:acm:.. (or) !ImportValue xx
backend.jms.destination Your JMS Destination (queue or topic name) MY.BACKEND.TOPIC
backend.jms.parameters List of JMS connection parameters to be used in key:value form as described here. transport.jms.ConnectionFactory: 'My-ConnectionFactory'
backend.endpointType Optional, defaults to http. If you are using a non standard WSO2 extension, you might want to be able to override this. http, jms, lambda
securityScheme Optional, defaults to oath2. Supports mutualssl and oauth2. .
securityScheme.mutualssl Requires securityScheme.mutualssl.enabled and securityScheme.mutualssl.clientCert to be defined. .
securityScheme.mutualssl.clientCert Required with mutualssl, your client certificate chain in PEM (base64) format. It supports: a. File system - Path must be relative to where serverless.yml is located. b. AWS Certificate ARN c. AWS CloudFormation Export - Exported value must contain a valid AWS Certificate ARN. file://certs/backend.cer (or) arn:aws:acm:.. (or) !ImportValue xx
securityScheme.mutualssl.enabled Required with securityScheme.mutualssl. Expects true or false .
securityScheme.oauth2 Requires securityScheme.oauth2.enabled to be defined. .
securityScheme.oauth2.enabled Required with securityScheme.oauth2. Expects true or false .
securityScheme.oauth2.mandatory Optional with securityScheme.oauth2. Expects true or false .
securityScheme.oauth2.keyManager Optional with securityScheme.oauth2. Array of keys to be used by API
mediationPolicies Optional, your choice of mediation policies (or) sequences. They can manipulate input/output/fault messages as described here.
mediationPolicies.in Input mediation policy, it manipulates the request going to your backend. log_in_message
mediationPolicies.out Output mediation policy, it manipulates the response going back to your API consumer. json_validator
mediationPolicies.fault Fault mediation policy, it manipulates the fault handling. None
apiProperties Optional, List of API properties to be used in key:value form as described here. 'property1': 'value1'
maxTps Max. Transactions per second, used for throttling. 100
cors Optional, a CORS configuration to enable. Omit this property to disable CORS. See below for properties.
cors.origins String array of allowed origins. Default: ['*']
cors.headers String array of allowed headers. Default: ['Authorization', 'Access-Control-Allow-Origin', 'Content-Type', 'SOAPAction']
cors.methods String array of allowed methods. Default: ['GET', 'PUT', 'POST', 'DELETE', 'PATCH', 'OPTIONS']
cors.credentials Allow credentials (boolean). Default: false true
tags Tags as an array that show up in WSO2 console.
businessInformation Optional, business contact information to the APIs. When specified, it will overwrite the values specified in swaggerSpec.info.contact.email and swaggerSpec.info.contact.name properties
businessInformation.businessOwner Optional, business owner name
businessInformation.technicalOwner Optional, technical owner name
businessInformation.businessOwnerEmail Optional, business owner email
businessInformation.technicalOwnerEmail Optional, technical owner email
swaggerSpec Swagger 2.0 / OpenAPI 3.0 specification in YML

Parameter	What?	Usage Example
`enabled`	Default is `true`. When set to `false` explicitly, deployment of APIs on WSO2 will be skipped. Suitable for offline testing etc.	`true`
`host`	WSO2 API Manager Hostname	`wso2-apimanager.com`
`port`	WSO2 API Manager Port	`443`
`user`	Username with an optional tenant symbol.	`user@tenant`
`pass`	Password, supports Serverless Variables syntax.	`xxx`
`gatewayEnv`	Target gateway environment, as configured in your WSO2 installation.	`Production and Sandbox`

Parameter	What?	Usage Example
`name`	(CANNOT BE UPDATED LATER) Your API Name	`MyAwesomeAPI`
`version`	(CANNOT BE UPDATED LATER) Your API Version, which also forms a part of the API URL ultimately.	`v1`
`rootContext`	(CANNOT BE UPDATED LATER) Your API Context, which will be exposed by WSO2 API Gateway. Must be unique per Gateway Environment.	`/myawesomeapi`
`description`	Free-form text	`My Awesome API`
`visibility`	Supports `PUBLIC` (Visible to everyone) and `PRIVATE` (Visible to current tenant). Kept in the api for backwards compatibility. Please use fields for `subscriberVisibility` and `publisherVisibility`.	`PUBLIC`
`subscriberVisibility`	Visibility of the API in the developer portal. Supports `PUBLIC` (Visible to everyone) and `PRIVATE` (Visible to current tenant) and `RESTRICTED` (Visible to it's tenant domain and only to the user roles that you specify. You should provide the roles in the `subscriberVisibilityRoles`.).	`RESTRICTED`
`subscriberVisibilityRoles`	The user roles that are able to access the API in Store. Only applicable in combination with `subscriberVisibility`.	`admin`
`publisherVisibility`	Visibility of the API in the publisher portal. Supports `PRIVATE` (Visible to all logged in publishers/creators) and `RESTRICTED` (Visible to logged in publishers/creators with the roles that you specify. You should provide the roles in the `publisherVisibilityRoles`.).	`RESTRICTED`
`publisherVisibilityRoles`	The user roles that are able to access the API in Store. Only applicable in combination with `publisherVisibility`.	`admin`
`backend`	Supports `http` and `jms` backends. Note: One API definition supports only one backend.
`backend.http.baseUrl`	Your HTTP backend base URL. It supports: a. URL - Any valid HTTP URL. b. AWS CloudFormation Export - Exported value must contain a valid HTTP URL. This value is only being used for the Production Endpoint, the Sandbox Endpoint is not supported anymore	`https://backend:port/123` (or) `!ImportValue xx`
`backend.http.certChain`	Optional, your backend certificate chain in PEM (base64) format. It supports: a. File system - Path must be relative to where `serverless.yml` is located. b. AWS Certificate ARN c. AWS CloudFormation Export - Exported value must contain a valid AWS Certificate ARN.	`file://certs/backend.cer` (or) `arn:aws:acm:..` (or) `!ImportValue xx`
`backend.jms.destination`	Your JMS Destination (queue or topic name)	`MY.BACKEND.TOPIC`
`backend.jms.parameters`	List of JMS connection parameters to be used in `key`:`value` form as described here.	`transport.jms.ConnectionFactory: 'My-ConnectionFactory'`
`backend.endpointType`	Optional, defaults to `http`. If you are using a non standard WSO2 extension, you might want to be able to override this.	`http`, `jms`, `lambda`
`securityScheme`	Optional, defaults to `oath2`. Supports `mutualssl` and `oauth2`. .
`securityScheme.mutualssl`	Requires `securityScheme.mutualssl.enabled` and `securityScheme.mutualssl.clientCert` to be defined. .
`securityScheme.mutualssl.clientCert`	Required with mutualssl, your client certificate chain in PEM (base64) format. It supports: a. File system - Path must be relative to where `serverless.yml` is located. b. AWS Certificate ARN c. AWS CloudFormation Export - Exported value must contain a valid AWS Certificate ARN.	`file://certs/backend.cer` (or) `arn:aws:acm:..` (or) `!ImportValue xx`
`securityScheme.mutualssl.enabled`	Required with `securityScheme.mutualssl`. Expects `true` or `false` .
`securityScheme.oauth2`	Requires `securityScheme.oauth2.enabled` to be defined. .
`securityScheme.oauth2.enabled`	Required with `securityScheme.oauth2`. Expects `true` or `false` .
`securityScheme.oauth2.mandatory`	Optional with `securityScheme.oauth2`. Expects `true` or `false` .
`securityScheme.oauth2.keyManager`	Optional with `securityScheme.oauth2`. Array of keys to be used by API
`mediationPolicies`	Optional, your choice of mediation policies (or) sequences. They can manipulate input/output/fault messages as described here.
`mediationPolicies.in`	Input mediation policy, it manipulates the request going to your backend.	`log_in_message`
`mediationPolicies.out`	Output mediation policy, it manipulates the response going back to your API consumer.	`json_validator`
`mediationPolicies.fault`	Fault mediation policy, it manipulates the fault handling.	`None`
`apiProperties`	Optional, List of API properties to be used in `key`:`value` form as described here.	`'property1': 'value1'`
`maxTps`	Max. Transactions per second, used for throttling.	`100`
`cors`	Optional, a CORS configuration to enable. Omit this property to disable CORS. See below for properties.
`cors.origins`	String array of allowed origins. Default: `['*']`
`cors.headers`	String array of allowed headers. Default: `['Authorization', 'Access-Control-Allow-Origin', 'Content-Type', 'SOAPAction']`
`cors.methods`	String array of allowed methods. Default: `['GET', 'PUT', 'POST', 'DELETE', 'PATCH', 'OPTIONS']`
`cors.credentials`	Allow credentials (boolean). Default: `false`	`true`
`tags`	Tags as an array that show up in WSO2 console.
`businessInformation`	Optional, business contact information to the APIs. When specified, it will overwrite the values specified in `swaggerSpec.info.contact.email` and `swaggerSpec.info.contact.name` properties
`businessInformation.businessOwner`	Optional, business owner name
`businessInformation.technicalOwner`	Optional, technical owner name
`businessInformation.businessOwnerEmail`	Optional, business owner email
`businessInformation.technicalOwnerEmail`	Optional, technical owner email
`swaggerSpec`	Swagger 2.0 / OpenAPI 3.0 specification in YML

💡Tip : Organize your project files efficiently.

You can spread the configuration across multiple files, so you can manage it better. Bonus, you can use linters and validators effectively on your swaggerSpec.

serverless.yml:

custom:
  wso2apim:
    apidefs:
      - ${file('./myAwesomeAPI.yml')}

myAwesomeAPI.yml:

name: "MyAwesomeAPI"
version: "v1"
rootContext: "/myawesomeapi"
---
swaggerSpec: ${file(./myAwesomeAPI.swagger.yml)}

myAwesomeAPI.swagger.yml:

openapi: 3.0.0
info:
  contact:
    name: The Awesome Team
    email: xx@xx.com
paths:
  /pet:
    post:
      summary: Add a new pet to the store
      responses:
        "201":
          description: Pet created
        "405":
          description: Invalid input