Serverless Framework plugin to manage APIs on WSO2 API Manager.
- Serverless Framework 1.75 and higher
- Node.js 14 and lower
- WSO2 API Manager 2.6.0
- WSO2 API Manager 3.2.0
- Create, Update and Publish your API definitions via
sls deploy
. - Manage your API definitions via
sls info
andsls remove
. - Supports
HTTP
andJMS
backends with mediation policies & additional API properties. - Uploads backend certificates (including CAs) to enable HTTP/s connectivity with backends.
- Supports
Swagger 2.0
andOpenAPI 3.0
specifications and will publish them to WSO2 Store / Dev Portal. - Automatically detects the version of WSO2 API Manager running.
-
Discover it on npmjs.com @ here
-
yarn add -D serverless-wso2-apim
ornpm install --save serverless-wso2-apim
-
Then in
serverless.yml
add following entry to the plugins array:plugins: - serverless-wso2-apim
-
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.
Parameter What? Usage Example enabled
Default is true
.
When set tofalse
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 NameMyAwesomeAPI
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) andPRIVATE
(Visible to current tenant). Kept in the api for backwards compatibility. Please use fields forsubscriberVisibility
andpublisherVisibility
.PUBLIC
subscriberVisibility
Visibility of the API in the developer portal. Supports PUBLIC
(Visible to everyone) andPRIVATE
(Visible to current tenant) andRESTRICTED
(Visible to it's tenant domain and only to the user roles that you specify. You should provide the roles in thesubscriberVisibilityRoles
.).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) andRESTRICTED
(Visible to logged in publishers/creators with the roles that you specify. You should provide the roles in thepublisherVisibilityRoles
.).RESTRICTED
publisherVisibilityRoles
The user roles that are able to access the API in Store. Only applicable in combination with publisherVisibility
.admin
backend
Supports http
andjms
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 anymorehttps://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 whereserverless.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
. Supportsmutualssl
andoauth2
.
.securityScheme.mutualssl
Requires securityScheme.mutualssl.enabled
andsecurityScheme.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 whereserverless.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
. Expectstrue
orfalse
.securityScheme.oauth2
Requires securityScheme.oauth2.enabled
to be defined.
.securityScheme.oauth2.enabled
Required with securityScheme.oauth2
. Expectstrue
orfalse
.securityScheme.oauth2.mandatory
Optional with securityScheme.oauth2
. Expectstrue
orfalse
.securityScheme.oauth2.keyManager
Optional with securityScheme.oauth2
. Array of keys to be used by APImediationPolicies
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
andswaggerSpec.info.contact.name
propertiesbusinessInformation.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
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: [email protected]
paths:
/pet:
post:
summary: Add a new pet to the store
responses:
"201":
description: Pet created
"405":
description: Invalid input
- For a full list of backlog items, click here
- Create an issue here