Overview

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

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 Akamai 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

List applications

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

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

Create a new application

Creates a new application and returns its location.

providerApplicationId=appId1&applicationName=applicationPrettyName

Get an application

Retrieve a specific application.

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

Remove an application

Delete a specific application.

Modify an application

Updates an application and returns its location.

providerApplicationId=appId1&applicationName=applicationPrettyName

List customers

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

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

Create a new customer

Creates a new customer and returns its location.

providerCustomerId=custId1&customerName=customerPrettyName

Get a customer

Retrieve a specific customer.

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

Remove a customer

Delete a specific customer.

Modify a customer

Updates a customer and returns its location.

providerCustomerId=custId1&customerName=customerPrettyName

List pairs

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

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

Create a new pair

Creates a new pair and returns its location.

customerSurrogateId=123&applicationSurrogateId=456

Get a pair

Retrieve a specific pair.

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

Remove a pair

Delete a specific pair.

Modify a pair

Updates a customer and returns its location.

customerSurrogateId=123&applicationSurrogateId=456

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.

Response codes

The API responds with the following set of HTTP codes:

Last modified: 12/12/2016