SOA.JSON

Moved

As of stingray, this was moved to under repository




Building a heterogeneous API catalog is one of the main pillar to succeeded with the adoption microservices architecture. Having an API catalog for all the different type of APIs is key. The ability to create a heterogeneous  API catalog capable to automatically adapt and onboard all kind of different type of APIs is the way to go. Wether you have Legacy API, Passthrough endpoint, Smart endpoint, Function as a service endpoint, or Newly created API with any framework,  a holistic view of these APIs is a must with the ability to search, document, productize and view analytics.

SOAJS Gateway is unique by adapting and becoming aware of your exiting APIs. What you need to have is swagger file and soajs.json files in your repository 

Here is the content of soa.json, this file is needed when you activate a repository or when you add a passthrough endpoint from git.

soa.json for type=service
{
    "serviceName": "artifact",
    "serviceGroup": "Examples",
    "servicePort": 4100,
    "serviceVersion": "1",

	"description": "This is the decryption of your service",

	"tags": ["tag1", "tag2"],
	"attributes": {
		"att1": ["att1.1", "att1.2"],
		"att2": ["att2.1", "att2.2"]
	},
	"program": ["soajs"],

	"swaggerFilename": "/doc/swagger.yml",

    "maintenance": {
        "port": {
            "type": "inherit"
        },
        "readiness": "/heartbeat"
    },

    "type": "service",
    "prerequisites": {
        "cpu": " ",
        "memory": " "
    },

    "requestTimeout": 30,
    "requestTimeoutRenewal": 5,

    "extKeyRequired": true,
    "oauth": true,
    "urac": true,
    "urac_Profile": true,
    "urac_ACL": false,
    "tenant_Profile": false,
    "provision_ACL": false
}

SOAJS helps you orchestrating different type pf repositories, here is the soa.json for a repository with static content aka react, angular, etc ...

soa.json for type=static
{
  "type": "static",
  "name": "Backoffice"
}

VariableRequireddescriptionexample
serviceNameYesThe name of the service, has to be unique and not been used by other service at the API catalog.

If the repoName is : xx.pay.merchant-registration 
Then your serviName should be: merchant-registration

"merchant-registration"

serviceGroupYesThe group of the service, make sure you set the right group to properly display the service under the right group at the API catalog.

The serviceGroup should reflect the system the service belongs to

"Payment"

servicePortYesThe port of the service. make sure it is unique and not being used by any other service at the API catalog. 4100
serviceVersionYesThe version of the service. make sure it has the following syntax: a string of /[0-9]+(.[0-9]+)?/"1" or "1.1"
descriptionNoThe service description to appear in the API catalog UI"This is a string"
swaggerFilenameNoThe location of the service swagger file from the repository root. if not set soajs will look for swagger.yml or swagger.json at the root folder."/doc/swagger.yml"
typeYesThe following type are supported: static, service, daemon, multi, custom (anything else)if not set the default type will be custom.
extKeyRequiredNoTo turn on multi tenancy you need to have extKeyRequired set to truedefault value is true
oauthNoTo turn on oauth security for this service. 

default is false

soajs supports 2 types of oAuth

  • oAuth0 aka JWT or webToken
  • oAuth 2.0

soajs empowers you to turn on oAuth at many different levels

  1. At the service level by adding it to soa.json
    Adding it to soa.json means you want oauth to be on for this service by default

  2. At the service > environment level from the console under: develop tab → API catalog → service settings
    Adding it at the service settings gives you the flexibility to turn it on and off per service per environment, 
    Please note that this will overwrite soa.json  

  3. At the tenant level from the console under: manage tab → multi-tenancy
    Adding it at the tenant level gives you the flexibility to turn on or off oauth per tenant.
    Please note that this will overwrite the above 2 points
    Also you can specify the type of oauth you want (oauth0 or oauth2)
uracNoTo add to the request header the logged in user information 

This is supper useful when soajs gateway proxy the request to your service and you need to know who is the logged in user.

default is false

urac_ProfileNoTo add to the request header the logged in user profile information default is false
urac_ACLNoTo add to the request header the logged in user ACL information default is false
provision_ACLNoTo add to the request header the tenant ACL information default is false
requestTimeoutNoThe request lifetimedefault is 30 
requestTimeoutRenewalNoHow many times to renew the request lifetimedefault is 5
maintenanceYesThe heartbeat route to probe the health status of the service. 
example
{
 "port": {
    "type": "inherit"
        },
 "readiness": "/heartbeat",

 "commands": [
    {"label": "reload", "path": "/reload", "icon": "provision"}
        ]
}

Maintenance Icon
For maintenance SOAJS is using font awesome, checkout the available icons at https://fontawesome.com/icons?d=gallery 

For example, if you choose the wrench icon as follows :

example
{
 "port": {
    "type": "inherit"
        },
 "readiness": "/heartbeat",

 "commands": [
    {"label": "My Command", "path": "/mypath", "icon": "fas fa-wrench"}
        ]
}