serverless-wso2-apim

Serverless Framework plugin to manage APIs on WSO2 API Manager.

Compatible with

• Serverless Framework 1.75 and higher
• Node.js 14 and lower
• WSO2 API Manager 2.6.0
• WSO2 API Manager 3.2.0

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, oauth2, apiKey and basicAuth. .
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
securityScheme.apiKey	Requires securityScheme.apiKey.enabled to be defined. .
securityScheme.apiKey.enabled	Required with securityScheme.apiKey. Expects true or false .
securityScheme.basicAuth	Requires securityScheme.basicAuth.enabled to be defined. .
securityScheme.basicAuth.enabled	Required with securityScheme.basicAuth. Expects true or false .
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: [e-mail]
paths:
  /pet:
    post:
      summary: Add a new pet to the store
      responses:
        "201":
          description: Pet created
        "405":
          description: Invalid input

What's coming up?

• For a full list of backlog items, click here

Need Help?

• Create an issue here

License

MIT