RESTful APIs – An accurate description

Hi everyone

Today I thought I would do a quick post to cover RESTful APIs, and what they are. The reason for this article is that I have, on numerous occasions, encountered developers (and indeed whole teams) who have misunderstood this concept at its very core. This causes a number of problems, firstly if you don’t understand RESTful APIs fundamentally, you’re likely to encounter integration issues quite early on. Secondly, unfortunately, if you’re a candidate interviewing for a role and haven’t understood what a RESTful API is properly, you’ll come unstuck in interview.

What RESTful is not (necessarily)

  • A buzzword for a JSON API
  • An API with obscure functionality

What a RESTful API is, and what it has

  • REST is REpresentational State Transfer, RESTful is an adjective, so a RESTful API is an API which subscribes to the REST principles
  • The purpose of REST is to ensure that APIs are easy to understand at a universal level
  • RESTful APIs will have end points which represent entities
  • Those endpoints will respect HTTP methods (also referred to as verbs) to represent the actions you wish to take

Okay, so explain to me the HTTP methods/verbs

  • GET requests represent reading this entity/collection from the data source
  • POST requests represent creating an entity/collection in the data source
  • PUT requests update (destructively, replacing) the entity in the data source
  • PATCH requests update (partially) the entity in the data source
  • DELETE requests remove the entity from the data source

How does that work in practice?

Let’s use the example of a payment provider, you may have entities such as

  • api/customer
  • api/payment
  • api/payment/paymentId/refund

You will always need a specification, but theoretically you know that if you send a POST to endpoint/customer you will create one, if you send a PATCH you’ll partially update that customer. If you send a POST to api/payment you will create a payment, for which you will receive a reference (ID), and if you were to send a POST request to api/payment/id-you-received/refund then you would create a refund against the payment which you specified in the payment ID.

So what’s the point?

The main idea behind RESTful APIs, the same as with other standards such as PSR-X, is to unify the way in which we build APIs, so if I were to say, for example, to an organisation with whom I am going to be integrating “we have a RESTful API you can integrate with” they know, with some level of certainty, how much work there is involved in working with it – they also do not have to have an in depth understanding of my local design, architecture, etc, because the RESTful design abstracts any need for that knowledge.

In summary

RESTful APIs are great, other APIs which are not RESTful can also be great. I just wanted to help inject some clarity on the topic, although, of course, there is plenty of information on the internet around this particular methodology. If one person reads this article and gains an actual understanding of what RESTful is, then it has served its purpose.

Edit: HATEOAS further reading

Valid point raised by DarkTechnocrat on Reddit, for further reading beyond a very basic understanding on REST, you probably should read up on HATEOAS – at a quick glance this article on spring.io looks like a good place to start 🙂

How to build a terrible API

Hi everyone

As you may know, throughout my career I’ve ended up doing a lot of integration development. Middleware, APIs, all that kind of stuff. So I thought I would write a quick list of the things you should definitely do to make your API really terrible for other developers to use, so that they put their heads through their desks trying to integrate with it.

Judging from some of the APIs I’ve had the misfortune of integrating with, I thought this was worth writing, for anyone who is building an API.

Obviously this post is humorous or satirical, if you like. Please, for the love of all that is good and sacred in this world, don’t follow these tips!

Tip #1 – Don’t write a darn thing down

No developer likes reading documentation, let alone writing it. So the best tip to make sure that everyone hates your API is to make sure you don’t write a single thing down. Not a thing, nada. Let them guess at how to use it and marvel at your ivory towered genius.

Tip #2 – Make sure that your API is totally inconsistent, especially with documentation

So if you did go to the effort of cobbling together some documentation, and this is critically important, you absolutely must ensure that it is totally out of date. It should be at least 2 major versions behind your developments to keep your job safe.

Also, make sure there are plenty of typos in field names, don’t spell check anything at all; and be sure to use plenty of three letter acronyms that only people within your organisation understand. This will make integration even more surprising.

Top tips for inconsistency include ensuring that you use an absolute minimum of three naming conventions, and at least four different response structures.

Tip #3 – Make sure you use all the wrong terminology

If your API is a straight-up JSON-POST API, which is really simple to use, make sure you throw in a few curve balls. Maybe some GET requests in there, maybe even the occasional PUT or PATCH. It just keeps things entertaining. Parse the API key in the header in some requests, a query string in others and part of the initial request object in the rest.

Also, make sure your account/client/public facing departments refer to your RESTful APIs as Fairy Liquid, and your SOAP APIs as Sleepy ones. This will make sure everyone finds your technical capacity fantastic and will marvel at your technological prowess.

Tip #4 – No version control

If you don’t make sure that your API is versioned, it will keep the developers integrating with it in work; because every time you change it they will have to rapidly drop all of their mission-critical developments to fix any integrations. Be sure to release a patch, break some calls, and then roll it back. Just to punish anybody not using version control on their integrations.

Don’t do anything silly like adding version control, or advanced warning of changes, and definitely don’t even think about doing Beta releases. That just takes the fun out of integration development.

Tip #5 – Throw as many random errors as possible

What you definitely shouldn’t do, under any circumstances, is have a unified and consistent way of handling errors, such as a resource not found or an API key not matching. These errors must be handled differently for every single possible error, on every single possible call.

This is really good for the economy, because it ensures that any developers integrating with your API will have to test every single possibility, against every single call you have. This will keep them in work. You’re doing them a favour, honest.

Why give a JSON error response back, detailing an error code and a human readable message, when a 404 or a 500 will do, that’s what they’re there for! Bonus points if you can throw a 301.

And you’re done.

If you follow these 5 simple rules, you will have a super-awesome-epic API built our of pure ivory, which people will have to pay you to integrate with, because nobody else will know how to.

Then you’ll become like Zuckerberg-cum-Gates rich and be proper leet hacker wizard man (or witch woman).

So there you have it. From someone who’s built, and integrated with, several (probably dozens of) APIs. The top list of things you should definitely never, ever, ever do, if you don’t want to burn in hell for the rest of eternity, stuck in an infinite loop of torture, ridicule and unknown fatal exceptions.

Peace out y’all! 🙂

I’d genuinely love to hear any additional tips you’ve got to build brilliant APIs, and your hilarious anecdotes which are only funny now because you’ve finished the course of therapy and sedatives and recovered from your caffeine addiction enough to laugh at them!