RESTful API Basics For Non-Technical Founders and Product Managers

From your website to your WiFi enabled Microwave (to your own product, maybe) almost everything uses some kind of API… but how exactly does a RESTful API work?

Before you continue reading, do consider that this post is written for non-technical founders and product managers. I’ll focus mainly on RESTful APIs in this post. I will oversimplify some concepts, and go into others in more detail.

With that in mind, let’s first understand why you need to know about APIs.

If you’re a product manager, founder, or have any other role which makes you responsible for product design, you must understand some basic technical concepts to make sound decisions. This will also help you make sure your team is following the right standards while building APIs.

What is API?

API stands for Application Programming Interface.

An API enables a web enabled application to fetch data from a server. The app communicates with the server via the API to let the server know what data it needs and in what form. The server then sends the requested data back to app via the API.

As you can make out from this (simplified) explanation, and API is used when two different applications need a common medium for communication.

Diving Deeper…

Simply put, an API is a way to communicate with a component without bothering with its internal functionality. An API usually expects input in a specified format and responds in a specified format as well.

The best analogy I’ve come across is that an API is similar to a restaurant. When you enter a restaurant, you’re given a menu. You select an item from it and tell the waiter to get it for you from the kitchen. You’re not aware about what happens in the kitchen, but the waiter delivers your the food on your table.

In this example, you are the web enabled application, your order is an API call, the waiter is the API itself, the kitchen is the application you are communicating with, the menu is the API documentation. You are not allowed to enter the kitchen, and the waiter can only deliver what the kitchen provides.

A washing machine (or any machine, for that matter) is an other way to think about APIs. A lot is going on inside the machine itself, but you don’t need to bother with it. The manufacturer has provided you with some buttons to control what you’re allowed to. The buttons are the interface through which you interact with the application.

RESTful APIs

Let’s shift gears a bit, and focus on RESTful APIs.

If you’re building a mobile app, a decoupled web app, or something which requires communication with a central server, chances are that you need to have an API backend. Usually products with a presence on multiple platforms develop APIs to have a common backend that will deliver predictable results across platforms. Most products use RESTful APIs for this purpose.

RESTful, or simply referred as REST APIs, use HTTP requests to GET, PUT, POST, or DELETE data. There are actually no firm rules for using these simple commands, but there are best practices for each :

Here are some examples of what you can do with REST API requests:

1. GET — /products to return list of products.
2. GET — /products/1 to return all data of a product (identified by 1).
3. POST — /products to create a new product.
4. PATCH — /products/1 to update partial data of a product (identified by 1).
5. PUT — /products/1 to update all data of a product (identified by 1).
6. DELETE — /products/1 to delete the product (identified by 1).

There are best practices for API response as well. I won’t dive deep into it, but to give you an idea let’s take a couple of examples. Continuing the above endpoints, “list of products” API will return list of data of each product. The data in this API is usually minimal, as sending all data of each product will increase response size unnecessarily. Apart from that,

1. GET method is usually used to read data only.
2. POST, PATCH, and PUT method is used to update/create data.
3. DELETE method is used to delete data.
4. GET method usually returns 200 HTTP response code.
5. POST method usually returns 201 HTTP response code.

There are a lot more technical things I’m tempted to mention here, but as I mentioned earlier I’m keeping this post easily understandable for non-technical individuals.

Let’s jump straight to things you should consider while developing APIs.

API Security Considerations

I mentioned earlier that making system open for public is a security hazard, even with credentials. What makes APIs secure? For starters, the public can only access and manipulate data which is allowed by APIs. Apart from that you can follow the following basic principles.

Always use SSL (HTTPS): Your users will be transferring data over network, and you can’t control their network security. What you can control is security of your application itself. Make sure your APIs are only accessible over HTTPS only.

Rate Limiting: Always have a reasonable limit for accessing APIs from one user over a fixed period of time. For example, you may set a limit of 60 API calls per user per minute to avoid abuse.

Authentication: There’s no one shot solution for authentication, but always use the most secure way to authenticate users over an API call, and make sure it supports a mechanism to logout user from server if needed.

Permissions: Double check API permissions. Without proper permission handling one user might be able to access or update another user’s data, or in some cases get super admin permissions!

Avoid Storing Sensitive Data on Client End: This is important, obvious, and one of the most common security hazard found in apps. Avoid storing sensitive data like API tokens, passwords, etc. on client side as in some cases it is very easy to get access and leak sensitive data. In case you do need to store such data, make sure you follow best practices for that particular platform or encrypt it if possible.

Some Important Points to Consider

API Documentation: If you’re working with a team or developing APIs for public use, always create a documentation for developers who will be working on the APIs. Even when you’re singing solo, documentation can come handy more often than you anticipate.

Some major API frameworks, like Django REST Framework, provide a way to generate documentation from code automatically.

Updates & Backward Compatibility: Here’s the thing about API based apps: you don’t have much control over what user has already downloaded. This is especially true in the case of mobile apps, as user might be using a version older than you’re currently working on.

Keep this scenario in mind, and ask users nicely to regularly update their version of app. You may use API versioning for major or breaking changes. Don’t ignore older APIs. Test them too when working on something new.

Prefer JSON: JSON APIs offer less overhead and wider support as compared to XML. Always prefer JSON based APIs, unless your use-case requires otherwise.

Next Steps

I hope by now you have some idea about APIs and how they work. I do not claim to have included everything you need to know about APIs in this post.

If you’re comfortable with what you’ve read so far, I’d recommend you to dive into some API development. This will really give you a much better understanding of how APIs really work.

Try How to write an API in 3 lines of code with Django REST framework as a starting point.

Crowdbotics helps non-technical people turn ideas and specs into working software products

If you have a project where you need additional developer resources, drop us a line. Crowbotics can help you estimate build time for given product or feature, and provide specialized developers as you need them. (We also support technical teams too! Learn more here, or try our app builder.)