Blog & News

Rest API

RESTful Services: REST API Development

Information Technology (IT) - 6 January 2016

As part of a rotating series of SOLABS technology posts, we’re speaking with our software engineers on their reflections on the industry in general, its development and rapid changes, and how this may be pertinent to compliance/regulatory and the future of EQMS software.

For this installment in the series, we’re talking with SOLABS’ Lead Front-end Developer, Pascal Demers about the web service architectural and development style, REST (Representational State Transfer) API1.

GORDON: Pascal, I’m told you’ve been working on RESTful development and the REST API for SOLABS recently. How would you explain REST to those of us who are not software engineers?

PASCAL DEMERS (PD): I can best explain REST using a web page metaphor. A REST web service is like a web page: it provides information, along with all the possible actions that can be performed from whatever given point. A client using the web service is like the user who navigates the web. They ask for some information, they get it, and then they chose from the available options to move on from there.

The only other apt metaphor I can think of is a Choose Your Own Adventure book, you know, those books that let you choose what the hero will do next, and then direct you to Page X if you want to flee, or to page Y if you want to fight? It’s an over-simplification, I think, but it gets across the point I am trying to make.

Returning to the web metaphor: I think that REST is really inspired by the way we interact with websites as users. HTML sites use hyperlinks and forms to let us interact with them. Their goal is to allow us (the client) to get the information we asked for, and to offer us options related to that information (links), and to choose where we go from there.

REST is based on the same principle. The client makes a request to the server, and the response they get contains the information requested (i.e., user information), along with the options possible from there (links to delete, update, lock/unlock this specific user).

GORDON: So, when did you start looking into the REST API for use with SOLABS?

PD: I really focused my interest on REST as an architectural and development style when I was asked to look into interactions between Office 365/SharePoint Online (MS) software and SOLABS QM. I jumped right in, of course [he laughs], and started looking at what was available through their API (Application Program Interface), and tried to make it work right from the start.

Since some MS software requires that users be authenticated to validate their access, we needed to implement a specific authentication mechanism for this, which is harder than it sounds since there’s not a lot of documentation to guide you for ‘pure JAVA‘ solutions.

The buzzwords ‘RESTful API’ would pop up every now and then. And then I started doing more research and reading on the REST API, and what we’re talking about now is basically the sum total of my knowledge of it.

"What it boils down to for me is that REST is more like an architectural style that a client can use to interact with data easily, without needing to know much about the server/API itself."

Pascal Demers
Lead Front-end Developer, SOLABS

GORDON: So as I understand it, are we talking about the same framework in a new, different way?

PD: Not exactly. What it boils down to for me is that REST is more like an architectural style that a client can use to interact with data easily, without needing to know much about the server/API itself. Even if most explanations about REST refer to the HTTP protocol, one could implement a RESTful solution without relying on HTTP in any way–it’s just a way to design/implement things.

A 100% RESTful implementation would require pretty much no knowledge on the client’s part beyond a generic understanding of hypermedia. The client would interact entirely through the hypermedia provided dynamically by the application. The client only needs an entry point, from which the possible actions (URI) would be provided by the server to the client in the response. At every step of the interaction, the server would return the possible paths the client could take from there. In this way, the server can evolve independently without impacting the client.

GORDON: So what is possible with the REST API that is not otherwise possible? I’ve read that it’s an architecture style “for building scalable web services” (SOLABS-appropriate!) that is able to increase performance and scalability—so ‘faster and bigger’ is a key benefit?

PD: I wouldn’t say it necessarily enhances performance. It’s more that it opens up your services to make them easier to use by others.

In theory, it should provide clients an easy interface for interacting with the server data. RESTful requests should return the URI(s) needed to perform anything on a specific object, which means the client’s developer doesn’t have to read much documentation to use the services. The client only needs to know how to use the media type and to parse the response appropriately (XML, JSON, etc.). So changes to the server could (in theory) be done without impacting the clients at all.

Example: If we get a user’s info from their ID, we also get the user’s information along with all the possible actions (complete URIs) available for that specific object. If, for some reason, URIs had to be changed, the client would not need to be updated for that, since the client automatically gets the updated URI.

GORDON: That`s where the REST API truly shines (at least, theoretically, and from what I understand of it so far)?

PD: Yes. REST is not limited to working with XML data, as with some other web service architectures (i.e. SOAP). And since REST can be used with JSON payloads (instead of strict XML that needs to be validated), it makes client development a lot easier (since JavaScript usage never stopped growing, and because using JSON is pretty much built into the language, as opposed to XML which is a lot more cumbersome).

GORDON: Why are we talking about this now, I mean, at this particular point in time?

PD: From what I recall, REST was developed over a decade ago. The reason it’s being talked about more and more now is probably because it’s meant to be simpler and easier to use (from a client point of view) than the alternatives, and because everything is being connected to everything else these days.

GORDON: Is there any cooperation required for engineers, developers, hardware manufacturers required for this to work, or is it already in use and just requires more knowledge/support?

PD: Well, first, the application must be developed and written with REST in mind. Clients also have to be written to use the service provided by the RESTful app. But once this is done, it should theoretically not require much from the clients’ point of view (the application could then be updated without much impact on any of the clients using it).

As with most services, there needs to be some kind of cooperation between the client and the service provider, but a RESTful service is (or at least should be) less dependent than most web services/interfaces are. Since the information and the available actions are exchanged between requests, a client should not use a strict API to use the services. It should be able to determine what they have access to, based on the URI contained in the payload and from there, be able to get what it needs automatically.

Because of that, changes to the application should not impact the clients (nor the documentation on how to use the service) in any way, which is kind of the beauty of a RESTFul design.

1Architectural Styles and the Design of Network-based Software Architectures by Roy Thomas Fielding

Tags: , ,