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

Service Provider 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

Create Managed Project API

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

Create Managed Project Request

{
	"accessKey": "QPAUEPLBLO9UHGEAJW7A",
	"secretKey": "Vcq8q9hNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW",
	"storageProvider": "AWS",
	"storageResourceIdentifier": "john-doe-blob-2",
	"storageRegion": "us-west-1"
}

Response

Create Managed Project 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

Create Managed Project API

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

Create Managed Project Request

{
		"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

Create Managed Project 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

Create Managed Project API

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

Create Managed Project Request

{
	"awsAccessKey": "ZLKQWILBLO9UHGEAJW7A",
	"awsSecretKey": "23mKlQhNtXz3o+ADkOPoq+JG81eu5dYotNwbEtiW",
	"kinesisEndpoint": "kinesis.us-east-2.amazonaws.com",
	"streamName": "john-doe-stream-2",
	"streamType": "LOCATION_DATA",
	"partitionKey": "partitionKey"
}

Response

Create Managed Project 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

Create Managed Project API

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

Create Managed Project Request

{
	"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

Create Managed Project 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

List Managed Projects API

curl -X GET \
  $BLUZONE_URL/portal/service/1/projects \
  -H 'bzspid: example-api-key' \
  -H 'cache-control: no-cache'

Response

List Managed Projects Response

[
    {
        "serviceProviderId": 1,
        "projectId": 2178,
        "accountId": 1823,
        "username": "owner@example.com",
        "projectName": "SP Create Test 0",
        "projectApiKey": "MZP9VuQxDX0MMU6eJn2SDvX0FsY4jUx2lqko8TWcDRZC7ByhU2",
        "debugEnabled": true,
        "dateCreated": 1507641990000,
        "dateUpdated": 1507641990000
    }
]