How do I make a Restful API?

As part of my Starting a Technology Start Up series, I’m covering core development concepts like – What is a Restful API? Why do I need a Restful API?

Most Tech start ups will be covering the ABCs of Tech Architecture at some point. I will do a post on it seperately, but what you need to know right now is simply that the A in ABC is APIs. APIs are the backbone of tech companies and drive all their applications, so it is very important to get it right.

So what is an API?

Let’s start with basics. An API is an application programming interface. In short, it is a way for you to interact with a programme though a defined process. Think of MacDonalds Drive Through – you don’t need to know how to make a burger, but you can go to the interface (the speaker/mic) and give your order then recieve the response (the meal) at the collection window. As long as you know what the request is, as well as the expected response – this works great! If you dont know how to make a request, you’re talking in an other langauge for example, or the response you get is wrong (i.e. you get the wrong order), this is bad!

So what is a Restful API?

Over 20 years ago in 2000, Roy Fielding came up with an idea for a new Architectural style that allowed for a decoupled applications to talk to each other in a controlled way. This is the beginnings of Representational State Transfer or REST. What makes REST great is simply that it only requires an API contract to be effective. You can write your underlying server code in PHP, C#, Java or whatever you want to present your API and response in an agreed way. Your front end or user client can equally be written however you want, but very commonly these days would be in a Javascript framework like Angular or React. Either way, you can have complete control voer two very seperate user experiences – Front and Back end can now focus on what they do best, rather than worry about both.

A Restful API follows a few basic principles. A core principle is that is is all about a representation of a resource and that this resource is accesible by a unique identifier with operations defined by verbs.

Let’s take an example of MacDonalds again. We start with a Restaurant (the location) and then create an order.

If you’re familiar with CRUD, (Create, Retrieve, Update, Delete) they can be loosely mapped to the Http Verbs used in Restful APIs.

  • Create – POST
  • Retrieve – GET
  • Update – PUT/PATCH
  • Delete – DELETE

A restful API defines a route, that allows access to a resource that returns the state of an entity. So a GET request to “https://myapi.com/restuarant/1” would return an object representing the state of the restaurant stored in the db with an Id of 1. A Post to “https://myapi.com/restaurant” would create a new restaurant resource in the db and return a standard response of ‘201 – created’ with a header containing a url to allow you to access it.

Nested resources or related resources are accessed using routing in the same vein. So a POST to, “https://myapi.com/resturant/1/order” would create a new order for restaurant 1.

There are different levels of maturity with Resful APIs. If you’re interested in the ‘perfect’ defintion, try googling HATEOAS.

So why do I need a Restful API?

I think at this point, I have already covered why a Restful API is important for businesses, but let me be explicit. It allows a business to seperate it’s front and back end resources to allow independent development and edployment on each. Imagine how powerful it is to be able to rebuild your entire user experience with a new website or app, without ever needing to change an API. Now, most of the time you will work on the APIs as well, to extend models or provide extended functionality – but it is not required. You can work only on what you want, when you want.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.