Skip to end of metadata
Go to start of metadata

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Mapping API Architecture

 

Production URL

The URL will have this basic structure: http://map-api.phunware.com/v1.1/{object}/{object id}

The object ID is used for resource operations for all methods in this document except for GET. For the mapping service, examples of objects are maps, POIs or resource types.

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.

HTTP Method

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 "http://cms-api.phunware.com/v1.0/containers/[id]"), treat it as a placeholder for the ID number of the item involved in the method (in this case, "GET /containers/12345" or "http://cms-api.phunware.com/v1.0/containers/12345").

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 and Partial Updates

With rare exceptions (e.g. segments), 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.

URL Definitions

The mapping web service will interact with the…

  • Cisco Mobility Services Engine (MSE) (via two POST methods: venue and floor)
  • Mapping SDK (via two GET methods: building and POI)
  • MaaS portal (via GET / PUT / POST / DELETE methods on two types of objects: point and resource)

GET Methods and 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. Here's an 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 

This URL-encoded, minified fragment is 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 after that:

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

ON THIS PAGE

  • No labels