Mobile Application Performance Ingest API v1

Ingest content for prepositioning by Akamai Mobile App Performance SDK-enabled apps, and edit and purge previously ingested content.

Learn more:


Overview

To control caching and increase performance, the Mobile Application Performance (MAP) software development kit (SDK) lets you pre-position frequently downloaded content on a mobile device, such as images and videos. Once this content is on the device, it’s ready whenever the application user requests it.

To pre-position content on a mobile device, you need to associate groups of users with appropriate content URLs. This process is known as ingesting content. The MAP Ingest API offers a programmatic interface that lets you segment application users into different groups and associate URLs with those segments. This gives you the flexibility to push suitable content to mobile devices at the appropriate time.

For example, you might call one user segment Bargain Shopper that loads new images from your sales on a daily basis.

Together, the MAP SDK and the MAP Ingest API give you the tools to build, expedite, and manage the best possible mobile experience for your Android and iOS users.

For details on the MAP SDK, see Get Started with the Mobile App Performance SDK.

Get started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named MAP Ingest API and set the access level to READ-WRITE.

  • Before running these operations, contact your Akamai representative to enable the MAP SDK for your account.

Resources

This section describes the API’s workflow and provides details on how to interact with each operation.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List applications GET /mobile-app-perf-sdk-api/v1/applications
Get an application GET /mobile-app-perf-sdk-api/v1/applications/{appId}/info
List segments GET /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest
Create new segments POST /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest
Update segments PUT /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest
Remove segments DELETE /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest{?segmentId}
List URLs GET /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest/{segmentId}/urls

List applications

Returns a list of MAP SDK applications enabled on your account.

GET /mobile-app-perf-sdk-api/v1/applications

Status 200 application/json

Object type: Application

Download schema: application.json

Response body:

[
    {
        "appId": 5000,
        "appName": "MAP-App1",
        "sdkKey": "MAP-App1-apikey",
        "activeDevices": 100
    },
    {
        "appId": 5001,
        "appName": "MAP-App2",
        "sdkKey": "MAP-App2-apikey",
        "activeDevices": 10
    }
]

Get an application

Returns a specific MAP SDK application enabled on your account.

GET /mobile-app-perf-sdk-api/v1/applications/{appId}/info

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/info

Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.

Status 200 application/json

Object type: Application

Download schema: application.json

Response body:

{
    "appId": 5001,
    "appName": "MAP-App1",
    "sdkKey": "MAP-App1-apikey",
    "activeDevices": 100
}
  1. Run List applications, then store the object’s relevant appId.

  2. Make a GET request to /mobile-app-perf-sdk-api/v1/applications/{appId}, which responds with an Application object.

List segments

Returns the existing content segments for a MAP SDK application.

GET /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/ingest

Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.

Status 200 application/json

Object type: Segment

Download schema: segments.json

Response body:

[
    {
        "segment": "map-segment-1",
        "modified": "2019-10-22T02:12:54966Z",
        "created": "2019-09-01T02:12:54966Z",
        "urlsNumber": 2
    },
    {
        "segment": "map-segment-2",
        "modified": "2019-10-22T02:12:54966Z",
        "created": "2019-09-01T02:12:54966Z",
        "urlsNumber": 2
    }
]
  1. Run List applications, then store the object’s relevant appId.

  2. Make a GET request to /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest, which responds with a Segment object.

Create new segments

Create new content segments for a MAP SDK application.

POST /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/ingest

Content-Type: application/json

Object type: Segment

Download schema: segment-ingest.json

Request body:

[
    {
        "segment": "map-segment-1",
        "urls": [
            {
                "url": "https://www.akamai.com/1"
            },
            {
                "url": "https://www.akamai.com/2"
            }
        ]
    },
    {
        "segment": "map-segment-2",
        "urls": [
            {
                "url": "https://www.akamai.com/10"
            },
            {
                "url": "https://www.akamai.com/11"
            }
        ]
    }
]
Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.

Status 204

  1. Run List applications, then store the object’s relevant appId.

  2. Build a new Segment POST object.

  3. POST the object to /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest.

Update segments

Modify the URL entries for a MAP SDK application’s existing content segments.

PUT /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/ingest

Content-Type: application/json

Object type: Segment

Download schema: segment-ingest.json

Request body:

[
    {
        "segment": "map-segment-1",
        "urls": [
            {
                "url": "https://www.akamai.com/1"
            },
            {
                "url": "https://www.akamai.com/2"
            }
        ]
    },
    {
        "segment": "map-segment-2",
        "urls": [
            {
                "url": "https://www.akamai.com/10"
            },
            {
                "url": "https://www.akamai.com/11"
            }
        ]
    }
]
Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.

Status 204

  1. Run List applications, then store the object’s relevant appId.

  2. Modify the contents of the urls array, optionally adding objects that represent new ingest content.

  3. PUT the object to /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest.

Remove segments

Removes existing content segments from a MAP SDK application.

DELETE /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest{?segmentId}

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/ingest?segmentId=map-segment–1

Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.
Required query parameters
segmentId String map-segment-1 Repeatable. A unique identifier for a segment.

Status 204

  1. Run List applications, then store the object’s relevant appId.

  2. Run List segments, then store the relevant segment value as the segmentId parameter.

  3. Make a DELETE request to /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest{?segmentId}.

List URLs

Returns a list of URLs for a MAP SDK application’s content segment.

GET /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest/{segmentId}/urls

Sample: /mobile-app-perf-sdk-api/v1/applications/5001/ingest/map-segment–1/urls

Parameter Type Sample Description
URL path parameters
appId Integer 5001 A unique identifier for a MAP SDK application.
segmentId String map-segment-1 A unique identifier for a segment.

Status 200 application/json

Object type: Segment

Download schema: segment-urls.json

Response body:

[
    {
        "url": "https://www.akamai.com/1",
        "added": "2019-09-01T02:12:54966Z"
    },
    {
        "url": "https://www.akamai.com/2",
        "added": "2019-09-01T02:12:54966Z"
    }
]
  1. Run List applications, then store the object’s relevant appId.

  2. Run List segments, then store the relevant segment value as the segmentId parameter.

  3. Make a GET request to /mobile-app-perf-sdk-api/v1/applications/{appId}/ingest/{segmentId}/urls, which responds with a Segment object.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

Application

Provides information about a MAP SDK application enabled on your account.

Download schema: application.json

Sample GET response:

[
    {
        "appId": 5000,
        "appName": "MAP-App1",
        "sdkKey": "MAP-App1-apikey",
        "activeDevices": 100
    },
    {
        "appId": 5001,
        "appName": "MAP-App2",
        "sdkKey": "MAP-App2-apikey",
        "activeDevices": 10
    }
]

Application members

Member Type Description
Application: Provides information about a MAP SDK application enabled on your account.
activeDevices Number Indicates the number of active mobile devices for the application.
appId Integer A unique identifier for the application.
appName String A descriptive name for the application.
sdkKey String Specifies the API key used to initialize the application.

Segment

Provides information about an application’s content segment.

Download schema: segment.json

Sample GET response:

[
    {
        "segment": "map-segment-1",
        "modified": "2019-10-22T02:12:54966Z",
        "created": "2019-09-01T02:12:54966Z",
        "urlsNumber": 2
    }
]

Segment members

Member Type Description
Segment: Provides information about an application’s content segment.
created String A time stamp for the segment, in ISO 8601 format.
modified String The time the segment last changed, in ISO 8601 format.
segment String A descriptive name for the segment.
urlsNumber Number Indicates the number of URLs in the segment.

Errors

This section provides details on the data object that reflects the API’s common response to error cases. It also lists the API’s range of response status codes for both error and success cases.

Error responses

This API responds with JSON objects that adhere to the HTTP Problem Details standard.

This example shows an error response to a request for a MAP SDK application that’s not available on your account. Refer to the incidentId when communicating with Akamai customer support.

HTTP/1.1 404 Not Found
X-Application-Context: Mobile App Performance SDK:sqa:23848
Vary: Accept
Content-Type: application/problem+json
Content-Length: 259
X-Trace-Id: a0485d94f3b1013a
Date: Wed, 02 Oct 2019 19:00:01 GMT
Connection: close

{
   "details":[
      {
         "field":null,
         "code":"#IE:ANF",
         "message":"Cannot find given application",
         "data":null
      }
   ],
   "code":"resource.not.found",
   "title":"Resource Not Found",
   "incidentId":"711a9466-e513-4c70-8315-18ac84ed3e08",
   "stackTrace":null,
   "resolution":null,
   "helpUrl":null
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation succeeded.
201 Resource successfully created.
202 Request accepted but not yet processed.
204 Successfully processed request.
300 Response offers a choice of redirect options.
301 The requested resource has permanently moved to the link provided.
302 The requested resource is temporarily available at the link provided.
303 The requested resource is available at the link provided.
400 Bad Request. This typically occurs due to a problem with the format of request data, such as an non-parsing or invalid body of data, or an invalid set of query parameters or values.
401 API authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 No permission to access this resource. This most likely reflects a limitation on the identity of the Control Panel user corresponding to the API client. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found. This typically occurs when a resource keyed by a URL path parameter no longer exists, or if the request URL is unreadable.
405 Method not supported. This typically occurs when the URL you’re calling responds to GET requests, but not PUT or DELETE.
408 Request timeout. This typically occurs when sending request data in batches, and failing to close out the request before the server timed out.
410 Requested resource is no longer available.
411 Missing Content-Length. When submitting request data, include a Content-Length header to declare its size.
413 Request body exceeds maximum allowable size.
415 Unsupported media type. This typically occurs when you request data in the wrong format, such as text/xml when the API can only exchange application/json data.
500 Internal server error.
501 Functionality not supported.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.
507 Insufficient storage for size of request. Try again later.

Last modified: 11/6/2019