A Party Inside The RESTful Academy

Expert Advice from Tech Elevator Instructor, Ben Langhinrichs

Read along with Tech Elevator Instructor, Ben Langhinrichs, as he talks “REST APIs” and the role that they play in Software Development.

a party inside the RESTful academy

Editor’s Note: This article was originally published to Tech Elevator Instructor Ben Langhinrichs’ Linkedin. You can visit the original post here.

Behind almost every web page there are services, and these web services are more often than not built with REST APIs.

But what is a REST API? The folks at Red Hat say “A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. REST stands for representational state transfer and was created by computer scientist Roy Fielding.”

Okay.

To simplify, a web API allows a client (an app or service which wants to do stuff) to make requests of a server (an app or service which controls the stuff), and then the server decides whether to honor the request or tell the client to bug off, but either way sends a response. This is known as an HTTP Request/Response cycle. A RESTful web API says that every request should stand alone so that the server can deal with that request and get rid of it as fast as possible without having to keep track of which other requests have already been made. Basically, a web services version of “50 First Dates” or “Groundhog Day”.

To get an idea of how REST requests work, let’s visit the Restful Academy.

restful academy

Restful Academy

Authentication and Authorization

When you get to the front door of the Restful Academy, you are met by a steely-eyed lady who demands your badge. If you don’t have one, she’ll grab you by the arm and frog-march you down the hall to the Main Office. There, they’ll grill you with questions, checking your various forms of id, and possibly even calling your mom to be sure you are who you say you are. Once they reluctantly admit you are, they will assign you a role, whether Visitor, Student, Teacher, or IT Demigod, and that will get stamped on your badge along with an expiration date, often the end of the academic year for Instructors and Students but the end of the day for a Visitor. Guard your badge carefully, as the Restful Academy takes security seriously.

Most REST APIs require dual steps of Authentication (proving who you are) and Authorization (determining by role or identity what permissions you have to access or add/update/delete resources). REST APIs are “stateless”, meaning every request requires you start from scratch, but to save constantly having to re-ask the same questions, a token of some sort is saved after the first call and can be passed along with every subsequent call. This is like the badge at the Restful Academy which allows you in for subsequent visits until some expiration date after which you need to do it all again.

Request/Response

With badge pinned to your lapel, you wander down the hall to the classrooms to learn or teach or do whatever IT folk do. Each room has a name, such as History or Math or PhysEd, so that you know what you’ll learn or teach or whatever in that room.

A well-designed REST API has named Endpoints which identify the collections of resources available for access. These Endpoints are URLs relative to the base API, so /parks provide access to a collection of parks, while /parks/Yellowstone would refer to the specific park. You could also have /parks/Yellowstone/moose as a collection of all moose within the Yellowstone park and /parks/Yellowstone/moose/Bullwinkle to pinpoint a particular moose.

Once you’ve decided which room to enter, probably Programming because who doesn’t like programming, you are met at the door by a steely-eyed gentleman (I sense a theme), who checks your badge and asks your purpose. If your id checks out, and your badge says you have permission to do the thing you came to do in the room you came to do it in, you can enter. If you came to learn, you learn. If you came to teach, you teach. If you came to erase whiteboards, you erase whiteboards. When you are done, you are given a shiny green star to wear on your shirt that says you have done your thing, and then you are sent on your way. But if your id doesn’t check out, or you don’t have permission to do that thing in that room at this time, you are given a a nasty red star to put on your shirt and escorted to the exit by a class monitor, usually a pasty-faced boy or girl who smirks at the thought of causing embarrassment.

Each request has a verb or method which specifies the request type. GET means you want to access information and take it back with you (i.e., ‘learn’). POST means you want to create a new resource (‘teach’ a new lesson), while PUT means you want to modify an existing resource (‘teach’ a lesson, but with some changes). DELETE means you want to get rid of a resource (‘erase’ the lesson off the whiteboard). Every request sends back a status code saying whether they could fulfil the request (a green or red star).

The rules are fairly simple. You can GET information, usually an entire lesson although sometimes you are allowed to ask questions (called query parameters), to limit how much of the lesson you must hear. This can be a great help, especially if it is a long boring lesson going through every single British king and queen in order. When you GET a lesson, you are not allowed to write anything on the whiteboard, so the questions you ask (query parameters) are the only real control you have.

If you have the Instructor role on your badge, or if it is a collaborative classroom, you may be authorized to POST information, which adds a whole new lesson to the whiteboards for students to GET, or you can PUT a new version of the lesson on the whiteboard. You bring the whole lesson with you, either way.

In some classrooms, Teachers or even Students may DELETE a lesson, wiping the whiteboard clean. For super valuable lessons, only an IT Demigod may DELETE the lesson, but everyone else is allowed to roll their eyes at his or her self-importance

Different requests may require information taken to the endpoint or returned from the endpoint. These are carried in the body of the request or response. Traditionally, GET takes nothing to the endpoint, but returns something in the body from the response. PUT and POST take something to the endpoint in the body, and may take something back, whether the complete information as in a GET or just a specific endpoint to identify the exact resource. DELETE doesn’t usually take or return information. There are other requests as well, but these are most common.

Whether you came to teach or learn or erase whiteboards, when you are done, you must leave with your star. No teaching two lessons at once, or both learning and erasing whiteboards. That is simply not allowed. You must leave and request to re-enter so that the steely-eyed gent (I really think he must be the steely-eyed lady’s brother) can decide whether you can do that thing you want to do.

There you have it, a REST API implementing an HTTP request/response cycle. Easy peasy!

Ready to take the next step in your career transformation? Take the Tech Elevator Aptitude Test.