Introduction to REST API

The HMG/HSG REST API is a Representational State Transfer (REST) Application Programming Interface (REST API). REST is a style of software architecture for distributed hyper-media systems such as the World Wide Web. REST provides a set of rules (constraints) to which an architecture should conform. This is in contrast to an "unconstrained architecture" in which services are free to define their own idiosyncratic interfaces.

REST provides a uniform interface between components, allowing them to communicate in a standard way. Requests use the standard HTTP methods; GET, PUT and DELETE requests can do only what is expected.

The effect is that your services are accessible through standard tools, and it is safe for other services and utilities to use yours in ways you did not predict.

Informational Links

Following are some useful external references to learn more about REST:

• Architectural Styles and the Design of Network-based Software Architectures (dissertation by Roy Fielding)
• Representational State Transfer (Wikipedia entry)
• How to Create a REST Protocol
• REST Anti-Patterns

Introduction to JSON

The REST API uses JSON (JavaScript Object Notation) to format API requests and responses. JSON is a lightweight data-interchange format that is easy for both humans to read and write, and machines to parse and generate. It is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, and Python.

JSON is built on two universal data structures, which are supported by nearly all modern programming languages:

• A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
• An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

A full description of JSON can be found at http://www.json.org.