Service Provider API
Inception
Resellers of Bluzone Cloud services (Service Providers) need an efficient way to create and manage projects on behalf of their end users. The Service Provider API enables project creation and management via a secure REST API.
Business Requirements
Service Providers must be able to create and manage projects with a REST API. The API shall support querying of Service Provider details, listing of managed projects, creation of managed projects and deletion of managed projects. The Service Provider API shall expose templating features
Elaboration
The Service Provider API is enabled for end users via a manual configuration step by Bluzone Administrators.
Service Provider Record
A Service Provider record is created in the main database. An API Key is generated and saved in the database, along with contact information about the Service Provider:
*NOTE: even if the access/secret key are the same for your default remote consumer and default remote storage, they must each be assigned a value.
Field | Type | Description |
---|---|---|
serviceProviderId | Long/Numeric | Auto generated provider id. |
name | String | A human friendly name for recognizing the service provider record. |
contactName | String | Agent or representative of the Service Provider. |
contactEmail | String | Email address for contacting the Service Provider. |
contactPhone | String | A phone number for contacting the Service Provider. |
templateProjectId | Long/Numeric | Optional field that maps to a project owned by the serviceProvider and to be used as a "template" to create other projects. |
apiKey | String | The access key for making api calls to the Service Provider API. |
dateCreated | String/Date | The timestamp of when this Service Provider record was created. |
dateUpdated | String/Date | The timestamp of the last time this Service Provider record was updated. |
accessKey | String | The access key for the default remote storage. |
secretKey | String | The secret key for the default remote storage. |
storageResourceIdentifier | String | The name (identifier) of the remote storage, e.g. the bucket name of an S3 bucket. |
storageRegion | String | The region of the remote storage, e.g. for S3 a region could be us-east-1. |
storageProvider | Enum | The storage provider. Current supported provider: AWS |
awsAccessKey | String | The access key for the default remote consumer. |
awsSecretKey | String | The secret key for the default remote consumer. |
streamType | Enum | The type of data that will be written to the default remote consumer. Current supported stream types: PACKET_DATA, LOCATION_DATA, POLICY_EVENT_DATA |
partitionKey | String | The partition key for the default remote consumer. |
streamName | String | The name for the default remote consumer. |
assumeRoleName | String | The name assumed role used after linking with AWS Account ID |
assumeRoleEnabled | boolean | To enable / disable Assumed role |
Supported APIs
API Name | Method | URL | Description |
---|---|---|---|
Get ServiceProvider Details | GET | <hostname>/portal/service/:serviceProviderId | Returns the metadata saved in the system about the ServiceProvider. |
Get List of Managed Projects | GET | <hostname>/portal/service/:serviceProviderId/projects | List of Projects managed by this ServiceProvider |
Get a Managed Project | GET | <hostname>/portal/service/:serviceProviderId/projects/:projectId | Get the details about a single Project managed by this ServiceProvider |
Create a Project | POST | <hosthame>/portal/service/:serviceProviderId/projects/_create?useDefaultRemoteStorage =<boolean>&useDefaultRemoteConsumer=<boolean> | Create a new managed Project using the values supplied in the request object. There are two query string parameters that you may provide; useDefaultRemoteStorage defaults to false, but when set to true the newly created project will use the default remote storage configuration associated with the service provider; useDefaultRemoteConsumer defaults to false, but when set to true the newly create project will use the default remote consumer configuration associated with the service provider. |
Delete a Project | DELETE | <hostname>/portal/service/:serviceProviderId/projects/:projectId | Delete a managed project. |
Update Default Remote Storage | PUT | <hostname>/portal/service/:serviceProviderId/_updateDefaultRemoteStorage?updateProjects=<boolean> | Updates the default remote storage configuration. The query string parameter updateProjects defaults to false, but when set to true will update all the projects that use the default remote storage configuration. |
Update Default Remote Consumer | PUT | <hostname>/portal/service/:serviceProviderId/_updateDefaultRemoteConsumer?updateProjects=<boolean> | Updates the default remote consumer configuration. The query string parameter updateProjects default to false, but when set to true will update all the projects that use the default remote consumer configuration. |
Examples
Get Service Provider Details
API Call
curl -X GET \ $BLUZONE_URL/portal/service/1 \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache'
Response
{ "serviceProviderId": 1, "name": "Example", "contactName": "John Doe", "contactEmail": "john.doe@example.com", "contactPhone": "+3055551212", "templateProjectId": null, "dateCreated": 1507252266000, "dateUpdated": 1507252266000, "accessKey": "AKIAIDLBLO9UHGEAJW7A", "secretKey": "DcE3uYhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "storageProvider": "AWS", "storageResourceIdentifier": "john-doe-blob-1", "storageRegion": "us-east-1", "awsAccessKey": "MKZNADLBLO9UHGEAJW7A", "awsSecretKey": "fdaADKQoidIQ2+Jf9FnqP+Hfiqo9naHodnau7Gba", "kinesisEndpoint": "kinesis.us-east-1.amazonaws.com", "streamType": "PACKET_DATA", "partitionKey": null, "streamName": "john-doe-stream-1" }
Update default remote storage
API Call
curl -X PUT \ $BLUZONE_URL/portal/service/1/_updateDefaultRemoteStorage \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "accessKey": "QPAUEPLBLO9UHGEAJW7A", "secretKey": "Vcq8q9hNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "storageProvider": "AWS", "storageResourceIdentifier": "john-doe-blob-2", "storageRegion": "us-west-1" }'
Request Body
{ "accessKey": "QPAUEPLBLO9UHGEAJW7A", "secretKey": "Vcq8q9hNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "storageProvider": "AWS", "storageResourceIdentifier": "john-doe-blob-2", "storageRegion": "us-west-1" }
Response
{ "serviceProviderId": 1, "name": "Example", "contactName": "John Doe", "contactEmail": "john.doe@example.com", "contactPhone": "+3055551212", "templateProjectId": null, "dateCreated": 1507736821000, "dateUpdated": 1508970844000, "accessKey": "QPAUEPLBLO9UHGEAJW7A", "secretKey": "Vcq8q9hNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "storageProvider": "AWS", "storageResourceIdentifier": "john-doe-blob-2", "storageRegion": "us-west-1", "awsAccessKey": "MKZNADLBLO9UHGEAJW7A", "awsSecretKey": "fdaADKQoidIQ2+Jf9FnqP+Hfiqo9naHodnau7Gba", "kinesisEndpoint": "kinesis.us-east-1.amazonaws.com", "streamType": "PACKET_DATA", "partitionKey": null, "streamName": "john-doe-stream-1" }
Update default remote storage - ARN Changes
API Call
curl -X PUT \ $BLUZONE_URL/portal/service/1/_updateDefaultRemoteStorage \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "storageRegion": "us-east-2", "storageProvider": "AWS", "storageTypes": ["BEACON_TELEMETRY_DATA"], "assumeRoleEnabled": true, "isAWS": true, "storageResourceIdentifier": "Test Resource Identifier service", "assumeRo leName": "arn changes-updated" }'
Request Body
{ "storageRegion": "us-east-2", "storageProvider": "AWS", "storageTypes": ["BEACON_TELEMETRY_DATA"], "assumeRoleEnabled": true, "isAWS": true, "storageResourceIdentifier": "Test Resource Identifier service", "assumeRo leName": "arn changes-updated" }
Response
{ { "serviceProviderId": 4006, "name": "goutham", "contactName": "Varma", "contactEmail": "goutham@bluvision.com", "contactPhone": "5615555555", "templateProjectId": null, "firmwareUpdateStrategy": "MANUAL", "dateCreated": 1565270469000, "dateUpdated": 1615806066000, "accessKey": null, "secretKey": null, "storageProvider": "AWS", "storageResourceIdentifier": "Test Resource Identifier service", "storageRegion": "us-east-2", "assumeRoleEnabled": true, "assumeRoleName": "arn changes-updated", "awsAccessKey": "MKZNADLBLO9UHGEAJW7AS", "awsSecretKey": "fdaADKQoidIQ2+Jf9FnqP+Hfiqo9naHodnaus7Gba", "kinesisEndpoint": "kinesis.us-east-1.amazonaws.com", "streamType": "LOCATION_DATA", "partitionKey": "", "streamName": "DennisStream", "awsAssumeRoleEnabled": true, "awsAssumeRoleName": null }
Update default remote consumer
API Call
curl -X PUT \ $BLUZONE_URL/portal/service/1/_updateDefaultRemoteStorage \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "awsAccessKey": "ZLKQWILBLO9UHGEAJW7A", "awsSecretKey": "23mKlQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "kinesisEndpoint": "kinesis.us-east-2.amazonaws.com", "streamName": "john-doe-stream-2", "streamType": "LOCATION_DATA", "partitionKey": "partitionKey" }'
Request Body
{ "awsAccessKey": "ZLKQWILBLO9UHGEAJW7A", "awsSecretKey": "23mKlQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "kinesisEndpoint": "kinesis.us-east-2.amazonaws.com", "streamName": "john-doe-stream-2", "streamType": "LOCATION_DATA", "partitionKey": "partitionKey" }
Response
{ "serviceProviderId": 1, "name": "Example", "contactName": "John Doe", "contactEmail": "john.doe@example.com", "contactPhone": "+3055551212", "templateProjectId": null, "dateCreated": 1507736821000, "dateUpdated": 1508970844000, "accessKey": "QPAUEPLBLO9UHGEAJW7A", "secretKey": "Vcq8q9hNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "storageProvider": "AWS", "storageResourceIdentifier": "john-doe-blob-2", "storageRegion": "us-west-1", "awsAccessKey": "ZLKQWILBLO9UHGEAJW7A", "awsSecretKey": "23mKlQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "kinesisEndpoint": "kinesis.us-east-2.amazonaws.com", "streamType": "LOCATION_DATA", "partitionKey": partitionKey, "streamName": "john-doe-stream-2" }
Create Managed Project API
If in the api call you include values for a remote storage or a remote consumer, the newly created project will use those configuration values and begin writing data to them. If you would like to use the default configuration for either remote storage or remote consumer DO NOT provided the associated parameters in the request, instead set the correct query string parameter to true. For example, if you would like to use the default configuration for remote storage but use a new remote consumer configuration, do not provide the values for the remote storage, but provide the values for the remote consumer and set the useDefaultRemoteStorage query string parameter to true.
Field | Type | Description |
---|---|---|
serviceProviderId | Numeric | Required ServiceProvider Id value. |
projectName | String | User friendly name to help identify this project - usually the company name and type, example: Acme Prod |
defaultOwnerEmail | String | Optional value that can be used as the Project owner's email and the username to login to the project. |
defaultOwnerPassword | String | Optional value that can be used for the user to login to the project via Bluzone Console. |
joinAccountsEnabled | Boolean | Default is false. When set to true, the system will associate projects with the same username as the owner. |
debugEnabled | Boolean | Default false. When true, the user will be able to login to this project via Bluzone Console using the provided defaultOwnerEmail as username and defaultOwnerPassword as password |
accessKey | String | Optional value for remote storage. |
secretKey | String | Optional value for remote storage. |
storageProvider | Enum | Optional value for remote storage. |
storageResourceIdentifier | String | Optional value for remote storage. |
storageRegion | String | Optional value for remote storage. |
awsAccessKey | String | Optional value for remote consumer. |
awsSecretKey | String | Optional value for remote consumer. |
kinesisEndpoint | String | Optional value for remote consumer. |
partitionKey | String | Optional value for remote consumer. |
streamType | Enum | Optional value for remote consumer. |
streamName | String | Optional value for remote consumer. |
API Call
curl -X POST \ $BLUZONE_URL/portal/service/1/projects/_create?useDefaultRemoteStorage=true \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "projectName": "SP Create Test 0", "defaultOwnerEmail": "owner0@example.com", "defaultOwnerPassword": "changeme", "joinAccountsEnambed": false, "debugEnabled": true, "awsAccessKey": "RT9OQLLBLO9UHGEAJW7A", "awsSecretKey": "9MLNHQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "kinesisEndpoint": "kinesis.us-east-2.amazonaws.com", "streamName": "john-doe-stream-2", "streamType": "LOCATION_DATA", "partitionKey": "partitionKey" }'
Request Body
{ "projectName": "SP Create Test 0", "defaultOwnerEmail": "owner0@example.com", "defaultOwnerPassword": "changeme", "joinAccountsEnambed": false, "debugEnabled": true, "awsAccessKey": "RT9OQLLBLO9UHGEAJW7A", "awsSecretKey": "9MLNHQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW", "kinesisEndpoint": "kinesis.us-east-2.amazonaws.com", "streamName": "john-doe-stream-2", "streamType": "LOCATION_DATA", "partitionKey": "partitionKey" }
Response
{ "serviceProviderId": 1, "projectId": 2178, "accountId": 1823, "username": null, "projectName": "SP Create Test 0", "projectApiKey": "MZP9VuQxDX0MMU6eJn2SDvX0FsY4jUx2lqko8TWcDRZC7ByhU2", "debugEnabled": true, "dateCreated": 1507641990350, "dateUpdated": 1507641990350, "beaconTemplates": null }
List All Managed Projects
API Call
curl -X GET \ $BLUZONE_URL/portal/service/1/projects \ -H 'bzspid: example-api-key' \ -H 'cache-control: no-cache'
Response
[ { "serviceProviderId": 1, "projectId": 2178, "accountId": 1823, "username": "owner@example.com", "projectName": "SP Create Test 0", "projectApiKey": "MZP9VuQxDX0MMU6eJn2SDvX0FsY4jUx2lqko8TWcDRZC7ByhU2", "debugEnabled": true, "dateCreated": 1507641990000, "dateUpdated": 1507641990000 } ]