Software as a Service (SaaS) Registration API

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 read all the sections and complete any tasks listed in the Getting Started with {OPEN} APIs section within the Introduction.

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.

Status Codes Description

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.

Actions

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

Errors

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 Listing

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.

Use Cases

The following use cases assume you have obtained an authorization from LUNA. You must substitute any HOST values in these use cases with your specific value. Also, you may have to replace the curl command with syntax specific to your client (e.g., egcurl).

About Contract IDs

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.

Use Case 1: Registering a New Customer

For this use case, 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:

[{"providerCustomerId":"custId1","customerName":"custName1","surrogateId":2},{"providerCustomerId":"custId2","customerName":"custName2","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
{
  "type": "https://problems.luna-dev.akamaiapis.net/-/resource-impl/forward-origin-error",
  "title": "Not Found",
  "status": 404,
  "instance": "HOST/config-saas-registration/v1/customers/1",
  "method": "GET"
}

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

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

{"providerCustomerId":"custId1","customerName":"custName1","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

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

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

Use Case 2: Registering an Application

In this use case, 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}]

Use Case 3: Creating an Customer/Application Pair

In this use case, 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 Use Case 1 and Use Case 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}

Use Case 4: Deleting a Customer

In this use case, 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

[{"providerCustomerId":"custId1","customerName":"custName1","surrogateId":2},{"providerCustomerId":"custId2","customerName":"custName2","surrogateId":3},{"providerCustomerId":"newCustId","customerName":"AutoSoft","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.

Use Case 5: Updating the Name of a Customer or an Application

This use case 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 use case, 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:

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

Last modified: 12/6/2016