REST API Core concepts

General

  • One URL defines a resource
  • Methods execute operations on resources
  • Operation is implicit (defined by the verb) and is not included in the URL

Formats

Carriots REST API can render responses in two formats:

  • XML
  • JSON

Request headers must specify desired format. If no format is explicitly defined, Carriots will render responses in JSON format. To specify a response format the request must include the header “Accept”:

  • For JSON format:
    • Accept: application/json (default Carriots REST API)
    • Accept: application/vnd.carriots.v2+json (explicit reference to version 2 of Carriots REST API)
  • For XML format:
    • Accept: application/xml (default Carriots REST API)
    • Accept: application/vnd.carriots.v2+xml (explicit reference to version 2 of Carriots REST API)

Responses rendered by Carriots will contain the “Content-Type” header:

HTTP verbs

  • GET: Retrieve element information
  • POST: Create an element
  • PUT: Update an element
  • DELETE: Delete an element

Responses will indicate allowed verbs. Example: Allow: GET, PUT, DELETE

API versioning

API version is specified in Accept header. When no version is specified, Carriots will assume last version available.

  • Request (header):
    • Accept: application/vnd.carriots+xml
    • Accept: application/vnd.carriots.v2+xml
  • Response:
    • Content-Type: application/vnd.carriots+xml; charset=utf-8
    • Content-Type: application/vnd.carriots.v2+xml; charset=utf-8

Dates

Carriots API REST Dates will be represented by strings with ISO 8601:2004 standard.

ISO 8601 standard “Data elements and interchange formats – Information interchange – Representation of dates and times” specifies date and times representation providing unambiguous notation and facilitates data migration between different systems.

		
Format:
	Year:
		YYYY (eg 2012)
	Year and month:
		YYYY-MM (eg 2012-10)
	Complete date:
		YYYY-MM-DD (eg 2012-10-06)
	Complete date plus hours and minutes:
		YYYY-MM-DDThh:mmTZD (eg 2012-10-06T17:35+01:00)
	Complete date plus hours, minutes and seconds:
		YYYY-MM-DDThh:mm:ssTZD (eg 2012-10-06T17:35:21+01:00)
	Complete date plus hours, minutes, seconds and a decimal fraction of a second
		YYYY-MM-DDThh:mm:ss.sTZD (eg 2012-10-06T17:35:21.45+01:00)

	where:

	     YYYY = four-digit year
	     MM   = two-digit month (01=January, etc.)
	     DD   = two-digit day of month (01 through 31)
	     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
	     mm   = two digits of minute (00 through 59)
	     ss   = two digits of second (00 through 59)
	     s    = one or more digits representing a decimal fraction of a second
	     TZD  = time zone designator (Z or +hh:mm or -hh:mm)
		

More details at http://en.wikipedia.org/wiki/ISO_8601