How To Make An API - Complete Guide

To see the youtube video where I explain the topic, please click here.

What Are APIs?

An API (Application Programming Interface) is basically a function over the internet, made over HTTP (the protocol that normal web requests use). It allows for certain functionality to happen, where the function exists somewhere on the internet and can be called from anywhere as long it's in the proper format has has correct authentication.

Common examples of API usage is for filling in content any time it's necessary in a website or app, or providing your API users with information from your database or some function to make it easy for them. For example, many times when websites load content (for example, item listings on Amazon), the pages aren't hard coded in HTML to load the details of specific items. Instead, the items exist as resources in a database, and an API is used to speak to that database to fill in HTML of the loaded web page based on a number of factors for the user. Another example is Google providing people access to their Google Maps API so they can use it for their apps or websites. 

APIs are very important and get used for basically any website or app that need some special work done (including speaking to a database or doing a special task). 

Consuming an API

An API can be called by simply using a URL, much like you'd use in your web browser. 

https://www.google.com/maps/search/?api=1&parameters

​If an API exists on the internet, there are three parts to properly 

1. The URL path. (The https://www.google.com/maps/search/ part)
2. The parameters included in the URL. (The stuff after the ? sign.)
3. The request body. (This isn't part of the URL.)

The URL path, parameters, and request body can all be customized to accept certain information for the request that you wish to make. (For example, for Google Maps API, we may choose to ask the API to give us an address if we give it latitude and longitude coordinates.) The implementation of the API is up to the developer. To see best practices, see this stack overflow question.

HTTP Methods (GET, POST, PUT, DELETE)

• Although the API can do whatever it wants, there are typical "Methods" used to describe the action that the API is going to perform. The four most common ones are POST, GET, PUT, DELETE). These match standard CRUD (Create, Read, Update, Delete) formatting. 

• POST - Send data to the server.
• GET - Get data from the server.
• PUT - Update data on the server.
• DELETE - Delete data from the server.

These methods get defined when you create your API.

Again, they're not actually part of some code or some magical rule that governs API servers...they're just convention. You could still make a deletion on a GET request, but that'd be considered poor practice. It's still possible. 

What an API Returns

There are two things that an API returns after making a request. The first is a response code. There are a bunch of response codes for different situations, and this website does a good job of going over them.

​The most important response codes are:

1. 200 - OK - The API request was good.
2. 400 - Bad Request - Some part of the request was bad. Maybe the user gave bad information.
3. 401 - Unauthorized - The user isn't authorized to access this API feature.
4. 403 - Forbidden - Some part of the API request isn't allowed to be done.
5. 404 - Not Found - The API trying to be called is invalid.
6. 409 - Conflict - Perhaps a resource trying to be used or updated isn't allowed to be.
7. 500 - There's some error with the API code and it isn't able to perform the request.

The other thing an API returns is the content that was requested, called the response body. This usually comes in json format, but unpopularly, it may also come in XML format.

Making an API

An API is created writing some functionality in a programming language (typically Java and NodeJS are most popular), and putting that code onto a server that sits there waiting for requests. Pretty simple, right? 

There are a few things that you should do if you want to create an API:

1. Plan exactly what your API should do, including the URL paths and functionality associated with the API.
2. Create a document for API usage in Swagger format. 
3. Pick the programming language that you want to create your API in. (Usually Java or Node.)
4. Start coding! Test the API locally.
5. Deploy your API code onto a server. Usually using a cloud service like Heroku is best.
6. Create a Postman collection to test all of your APIs endpoints.

Let's Create Our Own API

This blog post was the introduction to a series on APIs! We're going to, from start to finish, create our own APIs using Java and NodeJS, following all the steps along the way. 

The next step is to plan an API project and create the Swagger documentation. Click here to see the next article in this series, where we do that.

For the youtube video on the Introduction to APIs, watch it here:

Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels. 

Twitter: @srcmake
Discord: srcmake#3644
Youtube: srcmake
Twitch: www.twitch.tv/srcmake
​Github: srcmake

References:
1. stackoverflow.com/questions/25385559/rest-api-best-practices-args-in-query-string-vs-in-request-body
2. www.restapitutorial.com/httpstatuscodes.html
3. www.tutorialspoint.com/http/http_methods.htm