Carmageddon Back End API - version 1.0.0

The Carmageddon Back End API provides access to acquire data about cities, stations, pumps, and tanks used in the Carmageddon demonstration scenario. This API is used by the demonstration client to obtain information about the corporate resources, their locations, and processed analytic results.

The base URI for version 1 of the API is:

    http://api.carma.demo.ociweb.com/v1/...

The base URI includes the protocol, hostname and port, and a prefix path to the endpoint URIs. The prefix path includes the interface version of the API being accessed. Note that any changes to an existing version of the API will only extend it with additional parameters and endpoints, allowing existing clients to continue operation without modification when accessing the API.

Versions

Version numbering for the API is based on semantic versioning (http://semver.org/) and a client written to a major version is guaranteed to continue working for all subsequent minor and patch versions.

The current major version will always be available along with the immediately preceding major version. The major version 2 levels previous will be deprecated on release of a new major version and then obsoleted on the release of the next version.

This means that there will always be the current and two preceding versions of the API available for use. Use of the current version is always encouraged.

Data Formats

All data that is sent to or received from the Carmageddon Back End API is JSON encoded. The structure of the JSON data is defined as conforming to a specific schema that is well defined. The schema syntax followed is defined at http://json-schema.org/ and is itself defined in JSON format.

Media Type

The Carmageddon Back End API includes a media type to be used by the ‘Content-Type’ header to define the data being transfered from or to the server.

The API specific type for a pure JSON message content includes a required profile parameter that refers to the URI for the JSON schema definition.

• application/prs.com.ociweb.demo.carma+json;profile=<schema-URL>

  this media-type is for JSON data and includes a required profile parameter. The profile parameter value is used to define the allowable contents of the message data.

Schemas

Data schemas are defined using the http://json-schema.org schema definition mechanism. The schema JSON is available for use as documentation or for validation at the URIs given in the following sections.

The value of the profile parameter used in the media type definition is the URL to reach the file used to store the schema. The profile parameter values are used with the media types in the API description below to avoid repeating the schema description for each URI.

Collection Data

The collection data schema is used for data that includes more than one element in the message. The contained data elements are described using their own schemas described below, but the container schema describes how the multiple elements are included in the message.

Collection data is an object that contains some definition information along with an array of data elements. The data type of the elements is defined by the schema pointed to using the contentSchema URI property of the collection. The property holds a valid URI to the schema definition and the relationship of the property is a describedBy relationshop as defined in RFC5988 (http://tools.ietf.org/html/rfc5988). Inclusion of the contentSchema property is optional and can be inferred for most API calls.

The data property of the collection holds an array of elements of the same type. The type of data must be one of the valid API schemas as defined in this document.

The collection schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/collection.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Collection",
          "description": "Contains multiple elements of another type",
          "type": "object",
          "properties": {
            "contentSchema": {
              "description": "URI of the schema describing elements of the collection",
              "type": "string"
            },
            "data": {
              "description": "array of elements",
              "type": "array",
              "items": {
                "description": "element of the collection",
                "type": "object",
                "oneOf": [
                  { "$ref": "city.json#" },
                  { "$ref": "errordata.json#" },
                  { "$ref": "event.json#" },
                  { "$ref": "price.json#" },
                  { "$ref": "pump.json#" },
                  { "$ref": "revenue.json#" },
                  { "$ref": "station.json#" },
                  { "$ref": "tank.json#" }
                ]
              }
            }
          },
          "required": ["data"]
        }

City Data

The city data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/city.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "City",
          "description": "Describes information about cities",
          "type": "object",
          "properties": {
            "id": {
              "description": "unique identifier for this city",
              "type": "string"
            },
            "order": {
              "description": "externally defined ordering of this city in a list",
              "type": "number"
            },
            "zoom": {
              "description": "initial zoom level to use when showing the city on a map",
              "type": "number"
            },
            "city": {
              "description": "name of the city used for user viewable labels",
              "type": "string"
            },
            "state": {
              "description": "state abbreviation for the city",
              "type": "string"
            },
            "lat": {
              "description": "latitude of the city center",
              "type": "number"
            },
            "lon": {
              "description": "longitude of the city center",
              "type": "number"
            }
          },
          "required": [ "id", "order", "zoom", "city", "state", "lat", "lon" ]
        }

Station Data

The station data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/station.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Station",
          "description": "Describes information about stations",
          "type": "object",
          "properties": {
            "id": {
              "description": "unique identifier for this station",
              "type": "string"
            },
            "city": {
              "description": "viewable city name where the station is located",
              "type": "string"
            },
            "cityid": {
              "description": "unique identifier of the city where this station is located",
              "type": "string"
            },
            "lat": {
              "description": "latitude of station location",
              "type": "number"
            },
            "lon": {
              "description": "longitude of station location",
              "type": "number"
            },
            "tanks": {
                "description": "tanks located at this station",
                "type": "object",
                "properties": {
                  "regular": {
                    "description": "tankid value of the regular fuel tank located at this station",
                    "type": "string"
                  },
                  "premium": {
                    "description": "tankid value of the premium fuel tank located at this station",
                    "type": "string"
                  },
                  "diesel": {
                    "description": "tankid value of the diesel fuel tank located at this station",
                    "type": "string"
                  }
                },
                "required": ["regular", "premium"]
            },
            "pumps": {
              "description": "list of pumps located at this station",
              "type": "array",
              "items": {
                "description": "pumpId values for pump located at this station",
                "type": "string"
              }
            }
          },
          "required": ["id", "city", "cityid", "lat", "lon", "tanks", "pumps"]
        }

Pump Data

The pump data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/pump.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Pump",
          "description": "Describes information about pumps",
          "type": "object",
          "properties": {
            "id": {
              "description": "unique identifier for this pump",
              "type": "string"
            },
            "stationid": {
              "description": "unique identifier (reference) for the station where this pump is located",
              "type": "string"
            }
          },
          "required": ["id","stationid"]
        }

Revenue Data

The revenue data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/revenue.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Revenue",
          "description": "Describes information about revenue",
          "type": "object",
          "properties": {
            "scope": {
              "description": "scope of the revenue result",
              "enum": ["company", "city", "station", "pump"]
            },
            "id": {
              "description": "unique identifier for the scope of the revenue result",
              "type": "string"
            },
            "fuel": {
              "description": "fuel type for the revenue result",
              "type": "array",
              "items": {
                "description": "fuel type included in the revenue result",
                "enum": ["any", "regular", "premium", "diesel"]
              }
            },
            "from": {
              "description": "timestamp at beginning of interval for which revenue was collected",
              "type": "string"
            },
            "to": {
              "description": "timestamp at end of interval for which revenue was collected",
              "type": "string"
            },
            "amount": {
              "description": "revenue amount being reported",
              "type": "number"
            }
          },
          "required": ["scope","id","fuel","amount"]
        }

Maintenance Data

The maintenance data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/maintenance.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Maintenance",
          "description": "Describes a maintenance record",
          "type": "object",
          "properties": {
            "scope": {
              "description": "scope of the revenue result",
              "enum": ["station", "pump", "tank"]
            },
            "id": {
              "description": "unique identifier for the scope of the revenue result",
              "type": "string"
            },
            "maintenance": {
              "description": "fuel type for the revenue result",
              "type": "array",
              "items": {
                "description": "maintenance action record",
                "type": "object",
                "properties": {
                  "type": 
                    "description": "type of the maintenance record",
                    "type": "string"
                  },
                  "id": 
                    "description": "unique identifier for the item that was maintained",
                    "type": "string"
                  },
                  "detected": 
                    "description": "timestamp of when a failure was detected",
                    "type": "string"
                  },
                  "repaired": 
                    "description": "timestamp of when an item was returned to service",
                    "type": "string"
                  },
                  "description": 
                    "description": "description of the maintenance action",
                    "type": "string"
                  },
                  "action": {
                    "description": "the maintenance action",
                    "type": "string"
                  },
                  "notes": {
                    "description": "any additional notes regarding the action",
                    "type": "string"
                  }
                },
                "required": ["type","id","repaired","action"]
              }
            }
          },
          "required": ["scope","id","maintenance"]
        }

Event Data

The event data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/event.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Event",
          "description": "Describes information about events",
          "type": "object",
          "properties": {
            "scope": {
              "description": "scope of the revenue result",
              "enum": ["company", "city", "station", "pump","tank"]
            },
            "id": {
              "description": "unique identifier for the scope of the event list",
              "type": "string"
            },
            "events": {
              "description": "list of events",
              "type": "array",
              "items": {
                "description": "type of event being reported",
                "type": "object",
                "oneOf": [
                  { "$ref": "#/definitions/pumpfail" },
                  { "$ref": "#/definitions/pumpactive" },
                  { "$ref": "#/definitions/pumpinactive" },
                  { "$ref": "#/definitions/tankleak" },
                  { "$ref": "#/definitions/tankactive" },
                  { "$ref": "#/definitions/tankinactive" },
                  { "$ref": "#/definitions/tankfill" }
                ]
              }
            }
          },
          "required": ["scope","id","events"],
          "definitions": {
            "pumpfail": {
              "properties": {
                "type": { "enum": ["pumpfail"] },
                "id": {
                  "description": "unique identifier of the pump for this event",
                  "type": "string"
                },
                "when": {
                  "description": "whethis event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            },
            "pumpactive": {
              "properties": {
                "type": { "enum": ["pumprepaired"] },
                "id": {
                  "description": "unique identifier of the pump for this event",
                  "type": "string"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            },
            "pumpinactive": {
              "properties": {
                "type": { "enum": ["pumprepaired"] },
                "id": {
                  "description": "unique identifier of the pump for this event",
                  "type": "string"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            },
            "tankleak": {
              "properties": {
                "type": { "enum": ["tankleak"] },
                "id": {
                  "description": "unique identifier of the tank for this event",
                  "type": "string"
                },
                "rate": {
                  "description": "leakage rate that was detected",
                  "type": "number"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","rate","when"]
            },
            "tankactive": {
              "properties": {
                "type": { "enum": ["tankrepaired"] },
                "id": {
                  "description": "unique identifier of the tank for this event",
                  "type": "string"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            },
            "tankinactive": {
              "properties": {
                "type": { "enum": ["tankrepaired"] },
                "id": {
                  "description": "unique identifier of the tank for this event",
                  "type": "string"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            },
            "tankfill": {
              "properties": {
                "type": { "enum": ["tankfill"] },
                "id": {
                  "description": "unique identifier of the tank for this event",
                  "type": "string"
                },
                "when": {
                  "description": "when this event occurred",
                  "type": "string"
                }
              },
              "required": ["type","id","when"]
            }
          }
        }

Tank Data

The tank data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/tank.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "Tank",
          "description": "Describes information about tanks",
          "type": "object",
          "properties": {
            "id": {
              "description": "unique identifier for this tank",
              "type": "string"
            },
            "stationid": {
              "description": "unique identifier for the station where this tank is located",
              "type": "string"
            },
            "fuel": { "enum": ["regular", "premium", "diesel"] },
            "capacity": {
              "description": "fuel capacity of the tank",
              "type": "number"
            }
          },
          "required": ["id","stationid","fuel","capacity"]
        }

Error Data

Error data is included in response data when a status code other than in the 200 range is returned. This data is optional and its intent is to provide additional information about what caused the API call to fail. For example, if a call fails due to insufficient authorization, the message data can include a string stating this along with one or two links that can be used to login or register in order to obtain the proper authorization to make the call.

The error data schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/errordata.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "ErrorData",
          "description": "Describes information about errors encountered",
          "type": "object",
          "properties": {
            "reason": {
              "description": "cause of the error",
              "type": "string"
            }
          },
          "required": ["reason"]
        }

Id Lists

Some queries return a list of unique id values. These are formatted as a list of strings. The schema description filename and the media type parameter value is:

• http://oci-labs.github.io/carma-api/schemas/idlist.json

        {
          "$schema": "http://json-schema.org/draft-04/schema#4",
          "title": "IdLIst",
          "description": "Contains multiple elements of unique identifiers",
          "type": "object",
          "properties": {
            "idType": { "enum": ["stations","pumps","tanks"] },
            "data": {
              "description": "array of ids",
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["idType","data"]
        }

Access Semantics

Reading Resources

To read the content of resources, the HTTP GET method is used. The URI to the resource will determine if an individual resource, all resources, or some resources will be retrieved.

Reading the entire available resource list is done by simply calling the API GET method with the collection URI and no parameters. All data for that resource will be returned. An example of this API call is:

    GET /collection

It is also possible to page through the available resources. This is useful when there are many resources and the client wants to start using the available list prior to receiving the entire list; for example to start building a table in the user interface with the first entries before the entire set of data has been received.

Reading partial lists is done by providing query parameters to the GET method call that indicate the starting index (start) and number of entries (span) to return. The starting index is the offset in the entire list from the first entry. For example, calling

    GET /collection?start=51;span=50

will return the second 50 elements of the ‘/stations’ resource that are available. Clients should be aware that if the resource collection is updated between calls to these partial reads occur, the list being accessed will not remain unchanged.

Individual resources can be read by simply adding the {resourceid} value as the next element in the URI path:

    GET /collection/{rescourceid}

Searching for Resources

It is possible to search for resources of a type. This is done by using the HTTP GET method at a URI relative to the resource being searched for. Access from search is restricted to reading and effectively returns those records that meet the search criteria.

Search URIs will be formed similar to:

    GET /search/collection?query=<query-string>

Query string formats have not been finalized at this time.

HTTP Headers

The Carmageddon Back End ReST API requires and allows certain HTTP headers to be present in the request messages and provides headers in the response messages. These headers modify how the server responds to requests and provides additional information about the responses provided.

It is expected that the standard header mechanisms for caching, content negotiation, and connection management (among others) are handled externally to the API by the HTTP client and server libraries. They are not addressed here.

Request Headers

There are no additional request headers required for this API. Since the API provides only GET endpoints and parameters are supplied as either URI or Query parameters, no additional data needs to be sent as part of the request.

Response Headers

The Response headers in addition to standard headers that are provided by the API include Content-Type, and Retry-After. These headers provide additional information to the client for normal as well as exceptional response messages.

Content-Type Header

This header is sent when providing data in the response message. This header indicates what format the data is supplied in. As discussed in the data formats section above, this will be the API specific API format:

    Content-Type: application/prs.com.ociweb.demo.carma+json;profile=<schema-URL>

where the schema defined at <schema-URL> describes the details of the data format.

Retry-After Header

This header is sent with the 429 and 503 status code response messages. It will indicate the number of seconds to wait before retrying the request.

Status Return Codes

In response to HTTP requests, the API will return a status code along with HTTP response headers and any data for the call. The status codes indicate the result of the call and can be used to distinguish different reasons for the failure of an API call.

In addition to the response codes from the API, clients should be prepared to handle additional response codes that are generated by other elements within the web - such as 3xx codes and some 4xx and 5xx codes. Most of these other response status codes may be handled by the browser or library that is being used to make the remote API calls.

200 Ok

This status code indicates that the API call was successful and the requested operation was compelted prior to the response being sent.

204 No Content

This status code indicates that the API call was successful but that there is no content being returned. This will be sent only when the API defines that response data will be sent, and no data was available to send in the response. Calls that are defined to not return data simply return the 200 status code.

400 Bad Request

This status code indicates that the server was unable to parse the incoming API call correctly. The response data will typically include additional information about the failure cause.

404 Not Found

This status code indicates that the requested resource was not found on the server. The response may or may not include additional information about the resource. This may include advice on how to create the requested resource.

405 Method Not Allowed

This status code indicates that the API call was to a resource that does not support the requested HTTP method. The response will include the allowed methods in and HTTP Accept header.

429 Too Many Requests

This status code indicates that the client has been sending too many requests and the server is implementing rate limiting for this client. The response header may include an HTTP Retry-After header to indicate how much time should elapse before another call is made if the client wishes to avoid rate limiting.

500 Internal Server Error

This status code indicates that the server has encountered an error which it is unable to handle during the processing of the API call.

501 Not Implemented

This status code indicates that the client attempted to use a feature of HTTP (such as an extended feature like PATCH) that is not recognized by the server. This is different from the 405 code which indicates that the method is recognized but not allowed by the resource.

503 Service Unavailable

This status code indicates that the HTTP server is active, but the underlying server that implements the API is not available at this time. The server may send an HTTP Retry-After header if the cause is not due to resource starvation but to some known reason that is expected to clear.

Parameters used by the API

The Carmageddon Back End ReST API uses parameters in the formation of URIs in order to specialize the method calls. These parameters are either direct URI parameters, part of the URI path, or query parameters - added to the end of the path after a ‘?’ symbol and separated with ‘&’ symbols if more than one.

URI Parameters

The URI paramters used by the API are used to uniquely identify elements within the available data. Each element accessible by the API has a unique identifier that is unique within that elements type. This means that it is a mistake to attempt access of one type of data using an identifier for another (do not use a station Id to access a pump Id for example).

URI parameters are individual path elements in the URI. These parameters are not combined in this API, so each parameter stands on its own.

cityid

The {cityid} parameter is a string value that is used to uniquely identify each available cities resource. There should be no meaning attributed to the parameter value; specifically the value cannot be used as an index into lists or the dataset.

stationid

The {stationid} parameter is a string value that is used to uniquely identify each available stations resource. There should be no meaning attributed to the parameter value; specifically the value cannot be used as an index into lists or the dataset.

pumpid

The {pumpid} parameter is a string value that is used to uniquely identify each available pumps resource. There should be no meaning attributed to the parameter value; specifically the value cannot be used as an index into lists or the dataset.

tankid

The {tankid} parameter is a string value that is used to uniquely identify each available tanks resource. There should be no meaning attributed to the parameter value; specifically the value cannot be used as an index into lists or the dataset.

Query Parameters

The query parameters used by the API are used when accessing a collection for reading and used to restrict the access to a subset of the available data. These parameters will occur after the URI path, separated from the path by a ‘?’ symbol, and if more than one is present they will be separated with a ‘&’ symbol.

These parameters are of the form:

    <paramter-name>=<value>

where the <parameter-name> is one of those below.

start

The start parameter is used to indicate the first record to return in a restricted list of results. This is a numeric index into the list where the first record is at index 1. The list indexed is the one present at the time the request is received. If the list has been modified since the last call, the index may not reference the expected data. It is up to the client to determine if a list is complete or if the same list elements have been encountered when paging.

span

The span parameter is used to indicate the number of records to return in a restricted list of results. This number of records will be returned if there are enough after the starting index. If there are not enough elements to satisfy the request, then as many available records will be sent as possible. It is up to the client to check the length of the returned array to ensure that it does not attempt to access elements beyond the end of the list.

query

When a search URI is used, the query parameter is used to specify the criteria for the search. The value of this parameter corresponds to the ‘WHERE’ clause of an SQL ‘SELECT’ statement.

from

The from parameter is a string version of a date/time used to specify the starting time of an interval. This can be either a standard date format, a relative date format, or a numeric value representing the number of seconds since the epoch (01-01-1970). The special value of “first” is used to indicate the oldest available data in storage.

to

The to parameter is a string version of a date/time used to specify the ending time of an interval. This can be either a standard date format, a relative date format, or a numeric value representing the number of seconds since the epoch (01-01-1970). The special value of “last” is used to indicate the latest (possibly future) date available in storage.

fuel

The fuel parameter is used to restrict the amount of data returned in a list when requesting information about revenue. It has the special value of “all” that indicates that all fuels should be considered.

type

The type parameter indicates which single or multiple events types are to be included in a returned list of events. The event types can include the special value of “all” which indicates all events will be included. “all” is also the default value, so the lack of this parameter is the same as specifying "all". Values, other than “all” which are accepted include: "pumpfail", "pumpactive", "pumpinactive", "tankleak", "tankactive", "tankinacive", and "tankfill". More than one event type can be specified by including them as a comma separated list of types.

itemtype

The itemtype parameter indicates which types of items (pumps or tanks) are to be included in a list of maintenance records being returned. The special value of “all” indicates that records for item types should be included. Values other than “all” which are accepted include: ("tank", “pump”).