Skip to end of metadata
Go to start of metadata

API References

AndroidiOS

To view the method signatures, visit this link: http://phunware.github.io/maas-core-android-sdk/

To view the method signatures, visit this link: http://phunware.github.io/maas-core-ios-sdk/

 

 Architecture

Request/ Response Format

JSON is used for the request and response format. JSON is a lightweight and portable format that maintains human-readability.

When making POST or PUT requests, the request parameters MUST be JSON-encoded and placed in the request body. When making GET requests, the request parameters MUST be JSON-encoded, then URI-encoded and placed directly in the query string.

Clients should expect JSON-encoded responses for every request, even those that result in an error. The only exception is when uploading files using the S3 endpoints and the file is bigger than 2mb - you will receive a 413 error from Nginx.

HTTP Methods

Each method defines the HTTP method required depending on what the usage is. For example, if the method is used to simply get data, the HTTP method would be GET. If the method is used to delete data, it uses DELETE.

Date / Time Format

The date and time MUST be expressed in RFC 3339 format: YYYY-MM-DDThh:mm:ssZ

  • All times must be in the UTC time zone and indicated with a "Z". This is done to mitigate issues regarding Daylight Saving Time (DST).

  • No fractional seconds are allowed.

  • See section 5.6 of Date and Time on the Internet: Timestamps for more information.

Bracketed IDs ("[id]"s)

Whenever a bracketed ID ("[id]") appears in a method's name or URL (e.g. "GET /containers/[id]" or "https://cms-api.phunware.com/v2.0/containers/[id]"), treat it as a placeholder for the ID number of the item involved in the method (in this case, "GET /containers/58b72e03472f3f601810858f" or "http://cms-api.phunware.com/v1.0/containers/58b72e03472f3f601810858f").

Ellipses ("…"s)

Whenever an ellipsis ("…") appears in the JSON body, treat it as a placeholder for additional instances of the data that immediately precedes it.

PUT Methods & Partial Updates


There are a few differences in how the request parameters get handled by PUT methods:

  • There are no required parameters.

  • If a parameter IS NOT specified, it will retain its current value.

  • If a parameter IS specified, but with an empty value, then the value will be cleared.

  • If you pass in an identifier field for a container, schema, structure or content ID, it will be ignored.

GET Methods & Query Strings

The GET methods outlined in this document will use query strings, not JSON bodies, when making a request to a URL. This requires the user to convert JSON into a URL-encoded query string.

Example:

{ 
    "tags":  
    { 
        "any":  
        [ 
            "Zelda", 
            "Link" 
        ] 
    } 
}

Minified fragment using http://bigaqua.org/minify_json.html

{"tags":{"any":["Zelda","Link"]}}

URL-encoded, minified fragment using http://www.url-encode-decode.com/

%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

URL-encoded, minified fragment as the query string.



In order to compose a request, a "?" is appended to the end of the request URL, then the URL-encoded, minified fragment is added.

 

http://cms-api.phunware.com/v1.0/schemas?%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

Authorization

JWT Requirement

  • Authorization in CME API is handled using JSON Web Tokens (JWT), an industry standard for representing claims between two parties.

  • All endpoints require a valid, signed JWT issued from Phunware's LaaS system.
  • If no token is supplied, the API will respond with a 401 HTTP status code.

  • JWT expires in 24 hours

Setting the Header

In order to provide Phunware APIs with the JWT, you must provide a header named Authorization and the token must be prefixed with the word Bearer.

 

Key

Authorization

Value

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MTY3NCwiZW1haWwiOiJvcmdvd25lckBjeWJhZ2UuY29tIiwiZmlyc3RfbmFtZSI6IkN5YmFnZSIsImxhc3RfbmFtZSI6Ik9yZyBPd25lciIsIm9yZ3MiOltdLCJzZXNzaW9uX2lkIjoiNzk3ZWRjNmY2Mjk5Y2JmYmEyODE3NDlhMGFlZjI0YmNhNmZmODM0NSIsIm9yZ19pZCI6NTEsIm9yZ19uYW1lIjoiQ3liYWdlIENsZWFuIiwiaWF0IjoxNDg4MjI5ODY0LCJleHAiOjE0ODgzMTYyNjR9.Vd7BCYEkeWOq2B3_3Np9ylYDwYaAWyE1-e4ZvCIvK4E

Exceptions

The following endpoints do not require a JWT to be supplied.

  • GET /status

Response Handling

HTTP Status Codes

Success Payloads

Each successful response will include a JSON payload and the success code number.

200/201

Success

  • Used for general success.
  • Used when a POST operation results in the creation of a new resource (such that response should contain URI of newly created resource).

202

Accepted

Used when the clone process has been started successfully. The clone process will continue running in the background after the response is returned so it does not block the client.

Error Payloads

Each failed response will include a JSON payload that includes the error code number and message:

400

Bad Request

    • Used when one or more parameters are invalid.

    • Used when one or more required parameters are missing.

    • Used when the JSON payload is not valid JSON.

The actual message for this "Bad Request" error will vary depending on whether the error was caused by bad data sent in the request, a validation error when validating the request data or any other generic request error.


{
    "error": {
        "code": 400,
        "message": "Could not parse the request body."
    }
}

401

Unauthorized

Used when the operation fails authorization checks.

The actual message for this "Unauthorized" error will vary.


{
  "error": {
    "code": "UnauthorizedError",
    "message": "No authorization token was found"
  }
}

403

Forbidden

Used when the operation fails security checks (e.g. wrong app ID specified as input to retrieve specific data).

The actual message for this "Forbidden" error will vary.

 

{
  "error": {
        "code": 403,
        "message": "You are not allowed to delete this file."
    }
}

404

Not Found

Used when the requested resource does not exist (e.g. cloned container).

The actual message for this "Not Found" error will vary depending on what could not be found.

 

{
    "error": {
        "code": "server",
        "message": "File does not exist."
    }
}

423

Locked

Used when a clone process is in progress. Only one clone process can be started for a given organization.


The actual message for this error will vary. When attempting to clone a container that is already being cloned, for example, the following message would be returned:

 

{
    "error": {
        "code": "request",
        "message": "Cannot start clone process as there is an existing clone process already in progress for this container."
    }
}

500

Internal Server Error

    • Used when the (internal) server is down.

    • Used when a clone operation has failed.


The actual message for this "Internal Server Error" error will vary. For a failed container clone, for example, the following message would be returned:

 

{
    "error": {
        "code": "server",
        "message": "The clone process has failed: Error copying file in S3."
    },
    "data": {
        "orgId": <integer>,
        "name": <string>,
        "fromContainerId": <string>,
        "toContainerId": <string>,
        "type": <string>,
        "startedAt": <string>,
        "completedAt": <string>
    }
}
  • No labels