SaaS Registration API v1

Register SaaS applications and customers, and manage their associations.


Overview

This API allows you to specify the following REST resources for Software as a Service (SaaS):

SaaS Resource Description
application The ID of your organization’s SaaS application.
customer The ID of your customer who will have access to one or more SaaS applications.
pair A mapping between a SaaS application and a SaaS customer.

Here are details for each API object:

  • Applications represent your organization’s SaaS applications, which are hosted on the Akamai portal. The required members are the providerApplicationId and the surrogateId. The providerApplicationId is expected to match a value in a given request the identifies the application. It is expected to hold no more than 50 ASCII characters. The surrogateId uniquely identifies this object in the collection. A human readable name for a given application ID can also be specified.

  • Customers represent your organization’s customers of your SaaS applications. The required members are the providerCustomerId and the surrogateId. The providerCustomerId is expected to match a value in a given request the identifies the customer. It is expected to hold no more than 50 ASCII characters. The surrogateId uniquely identifies this object in the collection. A human readable name for a given customer ID can also be specified.

  • Pairs represent a pair of providerApplicationId and providerCustomerId values. These objects include a surrogateId that uniquely identifies them in the collection.

You can define human-readable names for the application and customer IDs.

These SaaS resources are tied to a contract. You need to specify the contract in each API operation.

Each available object has a globally unique ID which is referred to as the surrogateID in the API. You specify this ID when you operate on a specific object.

NOTE: When an operation includes the surrogateID for more than one object, the type of object is appended to the beginning of the variable name like applicationSurrogateId or customerSurrogateId.

Prerequisites

Before working with this API, you should familiarize yourself with the Get Started guide on provisioning Akamai APIs.

Input/output formats

Request input (POST/PUT body content)

Various calls may require you to use query arguments or form elements to pass additional content to the API.

Response output

This API uses the JSON, JavaScript Object Notation, response format.

For some operations a specific status code is returned in the response.

Variable values in input/output syntax

Throughout this document, variable values are shown enclosed in braces ({ }).

Unless otherwise stated, these braces denote that the value is a variable.

Examples

The following examples assume you have obtained an authorization from Luna Control Center. You must substitute any HOST values with your specific value. Also, you may have to replace the curl command with syntax specific to your client (e.g., egcurl).

The application requires the contract ID be specified in the request’s URL or you receive a NOT_AUTHORIZED error. References to CONTRACT in these operations should be replaced with your specific contract ID.

Example 1: registering a new customer

For this example, you register a SaaS customer with an ID of newCustId.

Prerequisite tasks

Before you begin, run the following GET query to verify whether the customer has already been entered into the system. This query returns your entire list of customers.

$ curl  HOST/config-saas-registration/v1/customers?contractId=CONTRACT

This query returns a JSON response in the following format:

[
    {
        "customerName": "custName1",
        "providerCustomerId": "custId1",
        "surrogateId": 2
    },
    {
        "customerName": "custName2",
        "providerCustomerId": "custId2",
        "surrogateId": 3
    }
]

THE response is a JSON array containing two customer records and includes the specific records in the system.

NOTE: If you try to fetch a record you do not have access to, or that does not exist, the query returns a 404 error similar to the example below.

Query example
$ curl  HOST/config-saas-registration/v1/customers/1?contractId=CONTRACT

{
    "instance": "HOST/config-saas-registration/v1/customers/1",
    "method": "GET",
    "status": 404,
    "title": "Not Found",
    "type": "https://problems.luna-dev.akamaiapis.net/-/resource-impl/forward-origin-error"
}

If the user specifies the correct value, they get the single object.

$ curl  HOST/config-saas-registration/v1/customers/2?contractId=CONTRACT

{
    "customerName": "custName1",
    "providerCustomerId": "custId1",
    "surrogateId": 2
}

Continuing with this example, the providerCustomerId needed is not listed, so you need to create it.

Creating a customerId

Creating a customer ID requires a POST to the collection resource. In the POST operation you need to specify a customer ID (providerCustomerId) and optionally a customer name (customerName).

The customerName specifies the value to display for this providerCustomerId in the reports available from the Akamai portal. The request returns a Location header for the new record.

$ curl -X POST -d 'providerCustomerId=newCustId&customerName=AutoSoft' HOST/config-saas-registration/v1/customers?contractId=CONTRACT

Another way to verify that the new customer has been added is to fetch the entire list:

$ curl HOST/config-saas-registration/v1/customers?contractId=CONTRACT

[
    {
        "customerName": "custName1",
        "providerCustomerId": "custId1",
        "surrogateId": 2
    },
    {
        "customerName": "custName2",
        "providerCustomerId": "custId2",
        "surrogateId": 3
    },
    {
        "customerName": "AutoSoft",
        "providerCustomerId": "newCustId",
        "surrogateId": 5
    }
]

The new record displays at the end of the list with a surrogateId of 5.

Example 2: registering an application

In this example, you register an application with a providerApplicationId of appId1.

Prerequisites

Before you begin, run the following GET query to verify whether the application has already been entered into the system.

NOTE: This query returns your entire list of applications.

$ curl  HOST/config-saas-registration/v1/applications?contractId=CONTRACT

The result of this query is an empty array ([ ]), which means no applications have been created for this contract.

The providerApplicationId is not listed, so you need to create it.

Creating the applicationId

Creating an providerApplicationId requires a POST to the collection resource. In the POST operation you need to specify an application ID (providerApplicationId) and optionally an application name (applicationName). The applicationName specifies the value to display for this providerApplicationId in the reports available from the Akamai portal. The request returns a Location header for the new record.

$ curl -X POST -d 'providerApplicationId=appId1' HOST/config-saas-registration/v1/applications?contractId=CONTRACT

The Location header specifies the link to this new object, you can also see it listed in the GET result to the collection.

$  curl  HOST/config-saas-registration/v1/applications?contractId=CONTRACT

[
    {
        "providerApplicationId": "appId1",
        "surrogateId": 0
    }
]

Example 3: creating an customer/application pair

In this example, you create a pair by registering, or associating, a given customer with an application. In this example the customer is newCustId and the application is appId1.

Prerequisites

First, verify whether both the given customer and the application are in the system. See Example 1 and Example 2 for details.

After verifying that the customer and application are in the system, check to see whether a pair for this customer/application combination has already been entered into the system. Run the following GET query against the entire collection return all configured pairs:

$ curl  HOST/config-saas-registration/v1/pairs?contractId=CONTRACT

The result is an empty array ([ ]) which means no pairs have been created yet for this contract.

Creating the pair

So now you have to create a pair by sending a POST request to the collection resource that specifies the surrogateId for both the application and customer. The POST request returns a Location header for the new record because it includes the -v argument, which turns on verbose logging. Verbose logging displays the Location header.

NOTE: In the following example, extraneous log output has been removed for brevity.

$  curl -v -X POST -d 'applicationSurrogateId=0&customerSurrogateId=5' HOST/config-saas-registration/v1/pairs?contractId=CONTRACT
...
< HTTP/1.1 201 Created
...
< Location: HOST/config-saas-registration/v1/pairs/0

The Location header specifies the link to this new object. You can use this link to view the new record, as shown in the following example:

$ curl HOST/config-saas-registration/v1/pairs/0?contractId=CONTRACT

{
    "applicationSurrogateId": 0,
    "customerSurrogateId": 5,
    "surrogateId": 0
}

Example 4: deleting a customer

In this example, you need to both delete a customer and remove all traces of the customer from the system, including any associated pairs.

Prerequisites

If the surrogateId of the record is known it can be used directly. Otherwise, you must first fetch the entire list:

$ curl HOST/config-saas-registration/v1/customers?contractId=CONTRACT

[
    {
        "customerName": "custName1",
        "providerCustomerId": "custId1",
        "surrogateId": 2
    },
    {
        "customerName": "custName2",
        "providerCustomerId": "custId2",
        "surrogateId": 3
    },
    {
        "customerName": "AutoSoft",
        "providerCustomerId": "newCustId",
        "surrogateId": 4
    }
]
Deleting the customer

The new record is at the end of the list, with a surrogateId of 4. You can issue a DELETE request to that ID.

$ curl -X DELETE HOST/config-saas-registration/v1/customers/4?contractId=CONTRACT

This operation deletes the customer, along with any pairs associated with that customer.

Example 5: updating the name of a customer or an application

This example is for an application, however, the update for a customer is virtually identical. If you want to use this operation for a customer, you’ll have to specify the customer endpoint and change the names of the parameters.

For this example, assume the surrogateId of the application in question is 0.

$ curl -X PUT -d 'applicationName=greatApp' HOST/config-saas-registration/v1/applications/0?contractId=CONTRACT

If desired, you can fetch the list again and verify that it was updated:

[
    {
        "applicationName": "greatApp",
        "providerApplicationId": "appId1",
        "surrogateId": 0
    }
]

Resources

This section provides details on the Network List API’s set of URL operations.

API summary

Operation Method Endpoint
Application
List Applications GET /config-saas-registration/v1/applications/{?contractId}
Create a New Application POST /config-saas-registration/v1/applications/{?contractId}
Get an Application GET /config-saas-registration/v1/applications/{surrogateId}/{?contractId}
Remove an Application DELETE /config-saas-registration/v1/applications/{surrogateId}/{?contractId}
Modify an Application PUT /config-saas-registration/v1/applications/{surrogateId}/{?contractId}
Customers
List Customers GET /config-saas-registration/v1/customers/{?contractId}
Create a New Customer POST /config-saas-registration/v1/customers/{?contractId}
Get a Customer GET /config-saas-registration/v1/customers/{surrogateId}/{?contractId}
Remove a Customer DELETE /config-saas-registration/v1/customers/{surrogateId}/{?contractId}
Modify a Customer PUT /config-saas-registration/v1/customers/{surrogateId}/{?contractId}
Pairs
List Pairs GET /config-saas-registration/v1/pairs/{?contractId}
Create a New Pair POST /config-saas-registration/v1/pairs/{?contractId}
Get a Pair GET /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}
Remove a Pair DELETE /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}
Modify a Pair PUT /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}

List applications

List all Applications associated with a given SaaS-provider-customer contract.

GET /config-saas-registration/v1/applications/{?contractId}

Example: /config-saas-registration/v1/applications/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

Status 200 application/json

Response:

[
    {
        "providerApplicationId": "appId1",
        "applicationName": "Example application",
        "surrogateId": "123"
    }
]

Create a new application

Creates a new application and returns its location.

POST /config-saas-registration/v1/applications/{?contractId}

Example: /config-saas-registration/v1/applications/?contractId=A–1234

Content-Type: application/x-www-form-urlencoded

Request:

providerApplicationId=appId1&applicationName=applicationPrettyName

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

URL-encoded form parameters:

Parameter Type Description
Required
applicationId String such as appId1. Deprecated. Use providerApplicationId instead. If both are specified, providerApplicationId is used.
providerApplicationId String such as appId1
Optional
applicationName String such as Example application

Status 201

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/applications/123

Get an application

Retrieve a specific application.

GET /config-saas-registration/v1/applications/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/applications/123/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

Status 200 application/json

Response:

{
    "providerApplicationId": "appId1",
    "applicationName": "Example application",
    "surrogateId": "123"
}

Remove an application

Delete a specific application.

DELETE /config-saas-registration/v1/applications/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/applications/123/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

Status 204

Modify an application

Updates an application and returns its location.

PUT /config-saas-registration/v1/applications/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/applications/123/?contractId=A–1234

Content-Type: application/x-www-form-urlencoded

Request:

providerApplicationId=appId1&applicationName=applicationPrettyName

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

URL-encoded form parameters:

Parameter Type Description
Required
applicationId String such as appId1. Deprecated. Use providerApplicationId instead. If both are specified, providerApplicationId is used.
providerApplicationId String such as appId1
Optional
applicationName String such as Example application

Status 204

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/applications/123

List customers

List all Customers associated with a given SaaS-provider-customer contract.

GET /config-saas-registration/v1/customers/{?contractId}

Example: /config-saas-registration/v1/customers/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

Status 200 application/json

Response:

[
    {
        "providerCustomerId": "custId1",
        "customerName": "Example customer",
        "surrogateId": "456"
    }
]

Create a new customer

Creates a new customer and returns its location.

POST /config-saas-registration/v1/customers/{?contractId}

Example: /config-saas-registration/v1/customers/?contractId=A–1234

Content-Type: customer/x-www-form-urlencoded

Request:

providerCustomerId=custId1&customerName=customerPrettyName

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

URL-encoded form parameters:

Parameter Type Description
Required
providerCustomerId String such as custId1
customerId String such as custId1. Deprecated. Use providerCustomerId instead. If both are specified, providerCustomerId is used.
Optional
customerName String such as Example customer

Status 201

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/customers/456

Get a customer

Retrieve a specific customer.

GET /config-saas-registration/v1/customers/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/customers/456/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 456 such as 456

Status 200 application/json

Response:

{
    "providerCustomerId": "custId1",
    "customerName": "Example customer",
    "surrogateId": "456"
}

Remove a customer

Delete a specific customer.

DELETE /config-saas-registration/v1/customers/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/customers/456/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 456 such as 456

Status 204

Modify a customer

Updates a customer and returns its location.

PUT /config-saas-registration/v1/customers/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/customers/456/?contractId=A–1234

Content-Type: customer/x-www-form-urlencoded

Request:

providerCustomerId=custId1&customerName=customerPrettyName

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 456 such as 456

URL-encoded form parameters:

Parameter Type Description
Required
customerId String such as custId1. Deprecated. Use providerCustomerId instead. If both are specified, providerCustomerId is used.
providerCustomerId String such as custId1
Optional
customerName String such as Example customer

Status 204

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/customers/456

List pairs

List all Pairs associated with a given SaaS-provider-customer contract.

GET /config-saas-registration/v1/pairs/{?contractId}

Example: /config-saas-registration/v1/pairs/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

Status 200 application/json

Response:

[
    {
        "applicationSurrogateId": 123,
        "customerSurrogateId": 456,
        "surrogateId": 789
    }
]

Create a new pair

Creates a new pair and returns its location.

POST /config-saas-registration/v1/pairs/{?contractId}

Example: /config-saas-registration/v1/pairs/?contractId=A–1234

Content-Type: customer/x-www-form-urlencoded

Request:

customerSurrogateId=123&applicationSurrogateId=456

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234

URL-encoded form parameters:

Parameter Type Description
Required
customerSurrogateId Number Integer such as 123
applicationSurrogateId Number Integer such as 456

Status 201

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/pairs/789

Get a pair

Retrieve a specific pair.

GET /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/pairs/123/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

Status 200 application/json

Response:

{
    "applicationSurrogateId": 123,
    "customerSurrogateId": 456,
    "surrogateId": 789
}

Remove a pair

Delete a specific pair.

DELETE /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/pairs/123/?contractId=A–1234

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

Status 204

Modify a pair

Updates a customer and returns its location.

PUT /config-saas-registration/v1/pairs/{surrogateId}/{?contractId}

Example: /config-saas-registration/v1/pairs/123/?contractId=A–1234

Content-Type: customer/x-www-form-urlencoded

Request:

customerSurrogateId=123&applicationSurrogateId=456

Parameter Type Sample Description
Required
contractId String A-1234 such as A-1234
surrogateId Integer 123 such as 123

URL-encoded form parameters:

Parameter Type Description
Required
customerSurrogateId Number Integer such as 123
applicationSurrogateId Number Integer such as 456

Status 204

Headers:

  • Location: https://CONSUMERID.luna.akamaiapis.net/config-saas-registration/v1/pairs/789

Errors

This section provides details on the API’s error response format, various possible types of error, and the full range of HTTP response codes including success cases.

Error responses

When a non 2XX HTTPS status code is returned, an error JSON such as the following is also returned:

HTTP/1.1 404 Not Found

Content-Type: application/json
Reply Body:

{
    "error": {
        "type": "https://akamai-api.com/myapp/errors/resource-not-found",
        "title": "resource not found",
        "detail": "resource 3 was not found in the system.",
        "instance": "http://akamai-api.com/myapp/account/12345/msgs/abc",
        "httpStatus": 404
    }
}

The returned HTTP error code corresponds to the httpStatus member; therefore, the caller does not have to query the headers for this information.

Error types

The following table describes the types of errors that may be returned.

Error Message Description
INVALID_ARGUMENT A failure occurred because of an invalid argument.
NOT_FOUND The operation referenced a resource that could not be found.
CONFLICT The requested operation could not be performed because of a conflict with an existing resource.
NOT_AUTHORIZED You were not authorized to run this operation. This error may occur if you did not specify the contractId.
BAD_REQUEST A failure occurred. Please check your request arguments.

Response codes

The API responds with the following set of HTTP codes:

Code Description
200 OK
201 Created
400 Bad Request. Please provide all the required parameters.
403 User is not authenticated.
409 Conflict
500 There is a problem processing your request. Please try again later. The details are provided in the response body.

Last modified: 12/12/2016