Related Topics
REST (Representational State Transfer) is a standards-based data architecture for sharing data between computers, using web-based access. Services that use REST are often called RESTful services. A REST service usually transfers data from a server-based data store to a client machine that requests it in a specified format—usually via a specifically configured URL.
The important thing to remember about REST services is that the server and client machines are unrelated. The activities on the client are completely unaffected by the activities of the server, and vice versa. Unlike a connection to a database like SQL server, the client machine does not need to store a connection string or maintain a constant connection to the server. Similarly, any changes to the code or operations of either machine have no effect on the other.
The only connection that occurs between the two systems is when the client machine sends a request to the server via URL, and the server responds by sending back data in a REST-compliant format. This "connection" is also stateless, which is to say that the server and client machines know nothing about each other, outside of a specific REST transaction. A REST transaction consists of a request from the client, and a response from the server that contains the requested data. The REST request must provide all of the information necessary for the server to respond to the request properly. The server cannot use any knowledge of past requests to complete the current request and return a response. Each transaction is made as if it was an entirely new request, unrelated to any previous requests.
REST is not a programming format. It is purely a set of architectural guidelines for the communications format used between two systems. As long as each machine knows which format to use for requests and responses, data can be shared. Because REST is an architectural construct, it is language-independent. REST services can be constructed in any programming language, and the programming language used by the client and server are irrelevant to each other. As long as both systems use the correct architecture for their communication, they can share data.
The REST Request #
A REST Request is a message sent to a server that asks for a response containing data. In most cases, a REST request is sent to an available URL. The URL may be publicly available as a service on the internet, or it may be available only inside the same network as the client. As long as the client can access the URL, however, it can request a REST response from the server.
The URL contained in the REST request is usually formatted in a specific way, in order to match the way in which the REST service is implemented on the server. For example, the REST service may require the URL be formatted hierarchically. A notional request URL for a publicly available REST Service that returns the current weather might be:
https://myrestservice.com/current/zip/92111
The server would interpret this request as asking for the current weather for the 92111 Zip Code.
Alternatively, the URL for the same information might require a URL that uses parameters, such as:
https://myrestservice.com?type=current&zip=92111
Both of these formats can constitute valid requests, as long as the server understands the format.
The REST Request may be more complex than shown above, and require additional information such as login credentials, specific HTTP header information sent with the request, and Key/Value pairs to provide parameters, or include other information. In Process Director, much of this additional complexity is hidden, but a fully formatted REST request with header information and Key/Value pairs to provide parameters for the data to return might look like this.
POST https://myrestservice.com/weather HTTP/1.1
Host: myrestservice.com
Content-Type: application/json
Content-Length: 42
{"Type":"current","Zip":92111}
Business Values have a feature for adding authentication credentials and Key/Value pairs to the HTTP header, as described in the Business Values topic of the Implementer's Guide.
The REST Response #
Once the server receives a valid request, the REST Response returns the requested data. Even if there's no data to return, the server will still send a response, to note that the request was received and fulfilled. The REST response will be presented in one of two formats, JSON or XML.
Both XML and JSON formats are used to represent data, though each one is very different.
XML is a highly-structured data language. Each element of data is presented in nodes that are set off by the <> characters, e.g.:
<temperature value="78.66" min="70.56" max="87.89" unit="fahrenheit"/>
JSON, on the other hand, is less highly structured than XML, and data is returned in a JavaScript-based format, e.g.:
"temperature": {"curr":78.66,"min":70.56,"max":87.89}
This format is not JavaScript, though it is based on the JavaScript language structure. Both JSON and XML are language-independent formats, and both are essentially formatted text files, though the formatting is, as we shall see later in this module, very important.
There are advantages and disadvantages between the two language formats.
- XML, because it's so highly structured, is very good at returning hierarchical data in a more easily comprehensible format. It's easier for humans to parse when, as we'll see later, we need to find specific data in an XML response. On the other hand, XML is relatively verbose, which means that, given the same data, an XML response might be significantly larger and take up more memory, than a JSON response.
- JSON, being less structured, is more flexible. A JSON response could structure the data in many different ways, while the highly structured nature of XML limits the way in which data can be returned. On the other hand, this flexibility means that two similar requests might return data that is structured slightly differently, meaning that the method you use to parse one request might not work on a similar one. Also, JSON's variable structure, and lack of a specific node structure can make JSON less readable and harder to parse by humans.
In general, JSON is a more popular format, due in part to its flexibility and versatility, but mainly because JSON responses are generally more lightweight than XML responses. There are still many REST services that return XML, or return both formats. In Process Director, both XML and JSON response formats can be used.
More Information about Rest Services
JSON and XML for REST: How sample XML or JSON REST responses might compare.
JSONPath and XPath: A comparison of the XPath and JSON Path syntax needed to parse XML or JSON REST responses.
Documentation Feedback and Questions
If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.
