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: [email protected]
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