REST API is the most popular Web API out there. Almost every self-respecting web site has one.
It is widely used to expose data, enable data manipulation, perform various actions, and lots more.
What’s more – implementing REST API is extremely easy. No matter what is your primary development platform – you’ll probably be able to build and deploy REST API quite easily.
However, there is a problem.
The Problem With REST API
Because REST API is so easy to implement, many developers and architects do just that – simply implement it, without investing too much thinking into its design.
And badly designed REST API is the worst thing that can happen to your API.
The reason for that is quite simple:
As an API developer, your main goal is to attract other developers.
In order for other developers to use your API, it must be, at least:
- Simple to use
- Easy to understand
Now, you might be thinking: “Well, what’s the problem? I have great docs for my API! The developers can understand exactly how to use my API by just reading the docs!”
You are a developer, right?
Do you like reading docs? Do you wake every morning, telling to yourself: “Yay! I’m going to read another API documentation today!” Yea, didn’t think so.
NEVER assume the developers will read your API docs. Your API should be easy to understand and predictable, and that’s what will attract developers to it.
How To Design Great REST API?
Great question, with a long answer.
There are a lot of factors that make or break REST API. For example – the URL.
URL is probably the most overlooked aspect of the API. Most developers and architects simply say: “Let’s slap the function name into the URL and call it a day”.
This way of thinking brought us abominations such as:
These URLs are so bad, it’s hard to decide where to start from.
First – verbs should never be part of the URL. Why? Simply: REST API already uses the HTTP Verbs defined in the HTTP standard for representing the type of action to perform.
So the full representation of the first example is actually:
Now try to read that as a simple sentence, in plain English (ignore the
api word). See the problem? We have something like: “Get the GetUsersById entity”. It’s not comprehensible.
However, if the API is designed like this:
We have a much simpler to understand API: “Get the user with the
Beautiful, isn’t it?
And there’s a lot more…
There are a lot of factors that contribute to designing great REST API, and I’m proud to introduce my newest course:
REST API Design – The Complete Guide
This online course have everything you need in order to design great REST API. The course discusses, among others, the following topics:
- What is API?
- What is Web API?
- Basics of REST API
- Using HTTP Verbs
- Crafting the URL
- Response Codes
- Performance Techniques
- And lots more…
The course does not require any prior coding experience, and is not targeted towards specific platform. We’ll be using specialized tools (Postman and Beeceptor) to simulate REST API client and server, and there will be no actual coding.
Here is a sneak peak of the first 3 lectures on the course:
Want to learn more?
Head over to the course page on Udemy, and start designing beautiful, professional REST API!
Oh, And One More Thing…
Designing REST API is one of the most important skills of a Software Architect. If you’re on your way to become one, then I would highly recommend to also take my first course, The Complete Guide to Becoming a Software Architect. This course takes you step by step on your way to becoming a great Software Architect, and discusses all there is to know about it. Learn more here!