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
Altair SmartWorks REST API can render responses in two formats:
- XML
- JSON
Request headers must specify desired format. If no format is explicitly defined, Altair SmartWorks 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 Altair SmartWorks REST API)
- Accept: application/vnd.altairsc.v2+json (explicit reference to version 2 of Altair SmartWorks REST API)
-
For XML format:
- Accept: application/xml (default Altair SmartWorks REST API)
- Accept: application/vnd.altairsc.v2+xml (explicit reference to version 2 of Altair SmartWorks REST API)
Responses rendered by Altair SmartWorks 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, Altair SmartWorks will assume last version available.
-
Request (header):
- Accept: application/vnd.altairsc+xml
- Accept: application/vnd.altairsc.v2+xml
-
Response:
- Content-Type: application/vnd.altairsc+xml; charset=utf-8
- Content-Type: application/vnd.altairsc.v2+xml; charset=utf-8
Dates
Altair SmartWorks REST API 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