REST - for the rest of us

What does REST stand for?

REST = REpresentational State Transfer

REST is an architectural style (design rules) of the Web introduced by Dr. Roy Fielding in his dissertation. Using a web browser to cruise the web is utilizing an environment that is an implementation of a REST-based design style. The protocol used by the web browser and the servers that deliver content to the browser are using HTTP. REST is the design style; HTTP is an example of an implementation using REST principles. If you use the ‘net you’ve experienced REST.

The following came from a presentation put together by Jody Bleyle and Jennifer Rondeau:

By the mid 1990’s, the Web had become the most successful distributed system in history. Roy Fielding was a computer scientist working on defining HTTP. He figured it would be a good idea to be able to describe what made the Web so successful so he and other people could use the information to make good decisions as the Web grew. So he set out to describe the architectural style of the Web. He called that architectural style “REST.” You’ll hear the parts of the style called “REST constraints” or “REST principles” or “REST design rules.”

What is a RESTful API? An API that uses the REST architectural style (which is the foundation of the Web). REST is not a technology. RESTful APIs use technologies built using REST principles. Web API designers want the same scalability and extensibility that makes the web itself so successful. So they decided to use the REST principles.

Absolutely marvelous! When would a normal (assuming a fairly loose definition of “normal”) user like me ever encounter REST?

Click here: (another browser window will be opened). There now you just used HTTP, an implementation of a protocol based on REST principles. Ready to go a bit further? Try this link: (another browser window will also be opened).

You should see the SUBMIT button on the bottom of the form. If you filled out the form and clicked on SUBMIT, well pat yourself on the back because you just used a REST-based design style again. That’s twice now and the day is young.

A design style you say. What other types of design styles are there?

Distributed computing has been forced to evolve over time due to different usage patterns. Back in the 80s and 90s distributed computing was confined to internal networks with a finite set of systems. With the arrival of the Internet, cloud-computing, mobile devices, and a global user community the old stuff just could not cut it. Technologies like DCOM and CORBA have been superseded by SOAP and REST. A few hundred desktop PCs communicating with a corporate server have been superseded by millions of smart devices (tablets, phones, watches, etc.) communicating with hundreds of thousands of applications and services.

Is it SOAP and REST – or – SOAP versus REST?

Generally versus. Plenty of content scattered across the web on the topic of REST vs SOAP. The general statement of “unless there is a compelling reason to use SOAP then use REST” is the guideline. Those who work directly with REST (developers) feel that a REST-based model is lighter weight and faster than SOAP. The trend for increased adoption of REST, regardless of the programming language used, has only gone up with the advent of mobile devices.​

There are still a few realms where SOAP has a role such as in back-end financial services or payment gateways (Rest vs Soap- NordicAPIs infographic Comparison). But REST is the design style for practically everything else. Even though REST is not a standard per se, most RESTful implementations make use of standards such as HTTP, URI, JSON, and XML.

To remain competitive and relevant in an era of smart devices organizations need a fast and flexible model to build and deliver content and services. REST provides this model. Programmers can continue to program in their language of choice. IT Operations can continue to manage their environments to deliver the services and content over HTTP like they’ve been doing for years. While REST is not perfect it is certainly a good model for today’s needs. What about tomorrow you ask. Working on the “Crystal Ball” app right now. And yes, it will be REST-based.

REST design principles? What are they?

Ok, you asked but join the club if the following make zero sense:

  • Client - server: Two separate components communicating with each other over a network. One provides a service (the server), the other requests it (the client).
  • Stateless: Sessions last for one request. The server doesn’t know the client exists except when the client makes a request.
  • Cacheable: Server responses indicate whether or not they can be cached.
  • Layered system: Components like proxy servers and gateways can exist between the client and the resources.
  • Uniform interface:
    • Resources: Have URLs and are endpoints.
    • Representations: Resources aren’t transferred directly between client and server, representations of them at a particular state are transferred over HTTP.
    • Self-descriptive Messages: Requests and responses contain all the information needed to process them and decide what to do next.
    • Hypermedia as the Engine of State (HATEOAS): Responses contain links that let the client move through the application. The goal is for RESTful consumers to browse the web programmatically, without human intervention.
  • Code on demand: An optional constraint that allows clients to download code.

What?!? No, really, what are the REST design principles?

Well those listed above are the design principles but trying to make sense of that list is not pain free. First, REST means communication happens over HTTP which is the protocol used on the web. Your devices know how to communicate using HTTP. Networks and those who manage the network know HTTP very well. In fact IT operations already have security measures in place to accommodate HTTP communications which the REST model takes advantage of. Like most internal combustion engines know how to run on fuels derived from oil anything connected to the network knows how to use HTTP.

Client – Server means that your device and my service are very independent. My service does not care what programming language your app is written in. My service does not care if you are using your laptop, smartphone, or television game console. My service does not even care if you talk to it once and disappear forever or your device just won’t be quiet. My service cares that you communicate using HTTP.

Likewise your device does not give a hoot about my service other than to use it. I’m just another stop on the information superhighway while you and your device are out on a joy ride. My service better be there and ready when you show up chattering away via HTTP.

You are the client; I’m the service. Let’s just keep it that way. No need to get all involved and stuff.

Your devices knows that this URL (also known as a URI) – https://some-place-on-the-net – means a place to go and that this URL https://some-place-on-the-net/mylocation-weather is a specific location (it may also be referred to as a resource endpoint). In the human world you have a place - Carnation Farmer’s Market and a specific location - booth 32, vegetable bin labelled “eggplant”.

When your device goes to mylocation-weather endpoint the content will be in an understandable format. HTML, the formatting standard for web pages might be used to contain your weather information. The data could also be contained in other formats such as XML (HTML is a form of XML) or in JSON. HTML looks like this:

<!DOCTYPE html>
        <meta content="text/html; charset=windows-1252" http-equiv="content-type">
        <title>My Weather Information</title>
        <meta content="The Weather Person" name="author">
        <p>Location= <span style="font-style: italic;">37.791035,-122.394768</span></p>
        <p>85F with sunny skies</p>

We all should be glad that our devices understand this stuff.

In the weather example REST means your device will provide its present location to a service endpoint and that service endpoint in turn will provide the device with a weather forecast for the general location your device provided.

There are also defined verbs or actions that can take place between endpoints – your device and the weather service. The verb set is designed to be small and stateless. The verbs include GET, PUT, POST, DELETE, and a few others. The verb GET is probably what our device will use to GET the weather. We might see the device use PUT if you want to add a favorites to your list of weather forecasts. The PUT may simply be the GPS/map coordinates for the PUT to your favorites list. It may also be the verb behind the SUBMIT button used above.

But you, as the device owner, are oblivious to all this back and forth verb usage with bits of data traveling between the device and all the services it has a relationship with. Quite the social butterfly that device of yours.

And these relationships are stateless. Communications between the device and the endpoints cannot assume a history of past interactions is maintained even if that interaction happened seconds ago. As a rule maintaining state consumes computer resources like server memory and/or storage. Plus a service may actually be delivered by multiple computers. Your device may communicate with Server-A for one transaction and Server-Z for the next. In a landscape where the news of the world is delivered in sound bites so has communication been mimicked in technology. Your social butterfly device is more a flirt than a story teller. Speed dating in the computer scene you might say.

In a REST design style the client side (your device, your browser) also caches content. The weather does seem to change often at times but your weather app does not need to constantly request updates from the weather service. Periodic updates work fine, say hourly. Of course if a tornado warning is raised for your area then the app may elect to ask for updates from the service much more frequently as well as directions to the nearest storm shelter. At least we hope so!

What’s it like being a service in this relationship?

Very nice you should ask. Not bad really. Sure there are millions of potential users all wanting content right this second but that’s it. The client provides the context of their request and the service provides the response. The service does not care about what programming or scripting language the client is using. The service already knows communication will happen over HTTP. And once the service fulfills the client’s request the service just moves on. Farewell. See ya later. Don’t let the door hit you in your HTTP before you close the connection.

How secure is REST?

A REST-based implementation like HTTP can be secure. HTTP’s secure cousin HTTPS provides a way to transfer data between your device and the end service securely. HTTPS provides a way to encrypt data in transit. HTTPS has been used for years. In fact if you have done any type of online financial transaction (shopping, banking, stock trading, etc), or logged in, or viewed personal information, or… then you have used HTTPS.

A REST-based implementation can utilize existing HTTPS for secure communications. But security at the end points (your device, my service) is the responsibility of those managing those endpoints. You control who uses your devices (or at least you should). The service provider should control who can do what within their service.

With anything technology-related there can be levels of complexity in implementing and managing it. Historically we have seen high-levels of apprehension when personal computers made their appearance in the workplace. Same was true of exposing corporate email. There were times when the only people I could email were others who worked for the same company.

The process of organizations becoming more “connected” was always a matter of implementing different technologies in different ways. There is always a learning curve and those whose raise concerns - both legitimate and some which are not.

One thing for sure - for technology to be secure it must be implemented properly. ForgeRock does provide consultation in how best to secure a REST architecture based on an organization’s requirements

Am I hearing that REST is changing the way security is enforced?

The truly wonderful thing about REST is that Developers, Business Managers, Solution Providers, etc are fully vested in REST because of the design style. They understand it and have been leveraging it (via the web and HTTP) for years. One of the reasons REST design principles are adopted is because of the lack of constraints - which is fine until we move into production.

Now security is required beyond just the communications channel. It needs to be a different security model than the old days, a model that works well with REST; a security model based on the identity of the user, the device, and the context of usage.

In the past, security was controlled at the firewall, at the perimeter of an organization’s various network layers. Perimeters no longer exist (or have had so many holes knocked through them that they have lost their value). Now that control surface is at the identity. The control surface, the security of a REST-based design style, is all about you in context such as:

  • Information about you
  • What groups or communities are you a member of (or not a member of)
  • What are your roles (parent, manager, bill payer, etc)
  • Where do you fit within an organization
  • Who do you report to
  • What entitlements do you have (or not have)
  • What resources are you attempting to access
  • What time of day are you trying to access those resources
  • What type of device is being used (is it registered and are you the registered owner)
  • What part of the earth are you presently on (and were you there five minutes ago)
  • How did you actually log in
  • Have you done this before
  • Is what you are about to do risky – get the weather versus withdraw from a checking account

The REST design style, and the people that work with it, don’t really want to be weighed down with all the identity and security stuff. At least not initially…

Which works very well for ForgeRock.

You don’t say! How does the ForgeRock’s solution add security to REST?

ForgeRock’s goal is to help enable an organization to establish and maintain secure, trusted relationships with identities both inside an organization as well as identities outside an organization all while utilizing a REST-based model. Our solution fully understands the REST model and can deliver much needed controls to services and their interfaces (APIs). Without changing the existing service ForgeRock can intercept HTTP traffic and mandate that the user authenticate. ForgeRock can then control access to the service based on policies.

As the graphic below attempts to show that without some form of identity management and access control the services can only deliver generic content:


Unfortunately without a scalable identity and access management solution added to the above architecture each service is left to its own to put something in place. This can equate to a poor user experience, added costs to delivering a service, and the loss of valuable insight on how users are utilizing the service. For that personal touch the service needs to know who you are:

With ForgeRock in the picture there is now a common way for you to identify yourself (authentication) and to help the services understand what you can access based on your context (authorization). While the REST design style still maintains independence between the client (you) and the services, ForgeRock’s solution adds a much needed layer of security to the endpoints. An organization can place ForgeRock’s solution in the HTTP communications flow between the client (you, your device, your app, your browser) and the target service thereby enabling identity-based security without disabling the good things of REST.

The ForgeRock solution can control access to service endpoints such as http://weatherworld/at-myhouse. When a user attempts to access http://weatherworld/at-myhouse ForgeRock can require that the user authenticate and then, based on policies, either permit or deny the user access. Without changes to the client or the service ForgeRock enables great security at the service endpoint. Better security based on your identity can lead to a better relationship between you and your service providers.

ForgeRock’s solution has been protecting HTTP-based endpoints for years. We have managed identities and the aspects of these identities at massive scale for years. With ForgeRock you can have your REST and security too.

Helpful Links

NSA Guidelines for Implementation of REST

1 Like