Serverless Platform Client SDK
This Serverless Platform Client SDK makes it easy to interact with the Serverless Platform and perform operations on it.
The SDK is light-weight, so that it can be used in the following: CLIs, Dashboards, Back-End Services, FaaS Layers. Please do not add any Node.js dependencies to this SDK, especially heavy ones.
This SDK should guide the interface design between Services and Clients. All Clients and Services must use the SDK and should never hardcode API endpoints or FaaS resources identifiers.
Quick-Start
Install the Serverless Platform Client SDK via NPM.
npm i @serverless/platform-client
If you are working with the dev
environment of the Serverless Platform, set the following environment variable, or configure the client programmatically, as detailed below.
export SERVERLESS_PLATFORM_STAGE=dev
Here is how you require, instantiate the Client and use it:
const { ServerlessClient } = require('@serverless/platform-client')
client = new ServerlessClient({
platformStage: 'dev',
accessKey: 'JA98JAJFASLFJSALFJASLFJ',
})
const instances = await client.listInstances('my-org')
ServerlessSDK
The Serverless Platform SDK Class
Kind: global class
- ServerlessSDK
- new ServerlessSDK(config)
- .config() ⇒
null
- .login([orgName], [orgUid])
- .getDomain(serviceName) ⇒
string
- .connect() ⇒
null
- .disconnect() ⇒
null
- .isConnected() ⇒
boolean
- .publish() ⇒
null
- .createComponent(orgName, componentName)
- .publishComponent(componentDefinition) ⇒
object
- .getComponent(componentName, componentVersion) ⇒
object
- .createInstance(orgName, stageName, appName, instanceName) ⇒
object
- .getInstance(orgName, stageName, appName, instanceName)
- .listInstances(orgName, orgUid)
- .run()
- .runFinish(method, instanceData)
- .deploy()
- .remove()
new ServerlessSDK(config)
Accepts a configuration block. See the config()
method for more information.
serverlessSDK.config() ⇒ null
Updates the SDK configuration
Kind: instance method of ServerlessSDK
Param | Type | Description |
---|
config.accessKey | string | Can either be a Serverless Platform Access Key or an ID Token. |
[config.platformStage] | string | The Serverless Platform Stage you wish to interact with. |
serverlessSDK.login([orgName], [orgUid])
[WIP] Logs users into the Serverless Platform. It opens up a browser to start the login process. This does not return anything. Instead, it opens up a browser to start the login process, creates credentials, then saves them in the current user's root folder, and then automatically configureds the SDK with those credentials.
Kind: instance method of ServerlessSDK
Param | Type | Description |
---|
[orgName] | string | The name of the Serverless Platform Organization you wish to log into. |
[orgUid] | string | The UID of the Serverless Platform Organization you wish to log into. |
serverlessSDK.getDomain(serviceName) ⇒ string
Gets a domain for a specific service: "engine", "registry", "events-streaming"
Kind: instance method of ServerlessSDK
Returns: string
- The domain of that service.
Param | Type | Default | Description |
---|
serviceName | string | null | The name of the Serverless Platform Service you want the domain for. |
serverlessSDK.connect() ⇒ null
Establishes a websockets connection with the Serverless Platform
Kind: instance method of ServerlessSDK
Param | Type | Description |
---|
options.org | string | Name of the Serverless Platform Org. |
options.onEvent | function | A function that handles events recieved from the Serverless Platform |
options.filter | function | Filters which events this connection should receive |
serverlessSDK.disconnect() ⇒ null
Disconnects a websockets connection with the Serverless Platform
Kind: instance method of ServerlessSDK
serverlessSDK.isConnected() ⇒ boolean
Checks if the SDK is currently connected to the Serverless Platform
Kind: instance method of ServerlessSDK
Returns: boolean
- Will return true if the websocket connection is active.
serverlessSDK.publish() ⇒ null
Publishes a Serverless Platform Event
Kind: instance method of ServerlessSDK
serverlessSDK.createComponent(orgName, componentName)
Returns a new Component as a Javascript object.
Kind: instance method of ServerlessSDK
Param | Type | Default | Description |
---|
orgName | * |
| The name of the Serverless Platform Organization. |
componentName | * |
| The name of the Serverless Platform Stage. |
serverlessSDK.publishComponent(componentDefinition) ⇒ object
This method publishes a Component to the Serverless Platform Registry. This method accepts a Component Definition (e.g. serverless.component.yml) as an object. In the Component Definition, it looks at the "main" property to find the path to the Component source directory. Then it collects that directory, adds in the special Component Handler, and packages everything into a zip file. After that, it fetches secure upload URLs and uploads the Component to the Serverless Registry. Once a Component has been uploaded to the Registry, the Registry must do some background processing to publish it, while that's happening, this method polls the API to see when the Component is finished being processed, and then returns the published definition.
Kind: instance method of ServerlessSDK
Returns: object
- The published Component definition is returned from the Platform API.
Param | Type | Description |
---|
componentDefinition | * | An object containing the properties of a Component. |
serverlessSDK.getComponent(componentName, componentVersion) ⇒ object
Get Component
Kind: instance method of ServerlessSDK
Returns: object
- Returns a Component definition from the Registry.
Param | Type | Default | Description |
---|
componentName | * |
| The name of the Component within the Registry. |
componentVersion | * |
| The version of a specific Component within the Registry. If this is not included, this method will always return the latest version. |
serverlessSDK.createInstance(orgName, stageName, appName, instanceName) ⇒ object
Returns a new Instance as a Javascript object.
Kind: instance method of ServerlessSDK
Returns: object
- Returns a new Instance definition as a Javascript Object.
Param | Type | Default | Description |
---|
orgName | * |
| The name of the Serverless Platform Organization. |
stageName | * |
| The name of the Serverless Platform Stage. |
appName | * |
| The name of the Serverless Platform Application. |
instanceName | * |
| The name of the Serverless Platform Instance. |
serverlessSDK.getInstance(orgName, stageName, appName, instanceName)
Get an Instance from the Serverless Platform by it's name and the names of its Organization, Stage, Application.
Kind: instance method of ServerlessSDK
Param | Type | Default | Description |
---|
orgName | * |
| The name of the Serverless Platform Organization. |
stageName | * |
| The name of the Serverless Platform Stage. |
appName | * |
| The name of the Serverless Platform Application. |
instanceName | * |
| The name of the Serverless Platform Instance. |
serverlessSDK.listInstances(orgName, orgUid)
List all Component Instances within an Org, given an org name or org UId
Kind: instance method of ServerlessSDK
Param | Type | Default | Description |
---|
orgName | * |
| Optional. Must include either orgName or orgUid. |
orgUid | * |
| Optional. Must include either orgName or orgUid. |
serverlessSDK.run()
Run
Kind: instance method of ServerlessSDK
serverlessSDK.runFinish(method, instanceData)
Run Finish
Kind: instance method of ServerlessSDK
Param | Type | Default | Description |
---|
method | string | null | The action that was performed on the Component. |
instanceData | object | | An object representing your Instance definition. |
serverlessSDK.deploy()
Performs a "deploy" action and polls the "getInstance" endpoint until its "instanceStatus" reflects a successful deployment, or error.
Kind: instance method of ServerlessSDK
serverlessSDK.remove()
Performs a "remove" action and polls the "getInstance" endpoint until its "instanceStatus" reflects a successful deployment, or error.
Kind: instance method of ServerlessSDK
F.A.Q.
How do I update the documentation?
Before publishing the client, be sure to update it's documentation by running: npm run docs
within the client
folder.
The reason this is kept in a separate library is because this SDK needs to be extremely light-weight, since it is used in back-end services built on AWS Lambda, as well as packaged into the Lambda Layer that is included within every Component Function in the Serverless Registry. The original Platform SDK contains many heavy NPM dependencies, increasing the overall package size, and slowing down the performance of any Lambda functions that use it.
© Serverless Inc.