API: Expect The Unexpected!
By: Surya Nirvana
Tags: Api Development, Backend, Backend Development, API

Source: unsplash.com

API, or an Application Programming Interface, is a set of functions or methods for building and integrating software. Quoted from howtogeek.com, think of it as a menu in a restaurant. A menu will consist of many dishes where you can choose what to order. When you’re done choosing, you tell the waiter/tress the dish that you want. The waiter/tress then proceed to the kitchen to prepare your dish. At this point, you don’t know what’s going on in the kitchen, and you don’t care about it; you only care about the food (of course). When they’re done preparing, they will serve the dish to you.

Similarly, as a developer, you choose what you want to request. You then send the request, then wait for the response. I think this is a perfect metaphor for describing API for common people. In that case, the request is telling the waiter/tress the dish you want, and the response is the finished dish.

Developers love APIs; it makes their life much, much easier. It helps us connect with services without knowing the implementation. For example, in my project BisaGo, we want the dashboard page to display the map. Coding the map is not that simple; it will have many lines of code. Instead of hard-coded it, we can use an API for the map that’s provided by Google.

From here, I’m going to talk based on my personal experience, and in my opinion, this is not the best practice. So you are welcomed to correct me if I’m wrong.

When creating an API, you have to consider some several things:

HTTP Method

HTTP implements several “methods” that tell which direction data is moving and what should happen. The two most common are GET, which pulls data from a server, and POST, which pushes new data to a server.

URL Endpoint

A URL describes the location of a specific resource, such as a web page. When you’re creating an API, you have to consider the endpoint or a URL where we can pull or push the data from the server.

Data Request

What data are you going to send to the server? What kind of data are you going to use to retrieve other data? Usually, we define the data request in this kind of form:

{

‘data_1’: ‘value’,

‘data_2’: ‘value’,

etc

}

Data Processing

After we get the data, what we want to do next? Do we want to save the data? Or do we want to use the data to retrieve other data? We don’t want the data gone to waste.

Response and Exception Handling

After we successfully process the data, we have to think about what we should return that indicates the process is successful. Not only that, but we also should return when there’s an exception or error occurred. We define the response in JSON format and the HTTP status code for all responses.

It’s very important to have a mindset “Expect the unexpected” when developing an API. We have to think about all of the possible cases that might happen. Consider this; we’re trying to create an API for form handling to store a record of the user’s weight. The form consists of a date, maximum weight, and minimum weight; the maximum weight value should always be more than the minimum weight value and the user can only record once per date. Here are the possible cases that could happen:

User put a valid data User didn’t fill in one of the fields User input the minimum weight value larger than the maximum weight value User already record with the same date that’s stored in the database

Creating an API to Update User’s Information

Relational Model of USER and BISAGO_USER

Method, POST since we want to push the data to the server, and we’re dealing with the user’s personal information (which is very confidential).

Endpoint, /update-user/ since the process is updating user’s information

Data Request,

{ 'email',

'name',

'phone_number',

'tanggal_lahir',

'jenis_kelamin',

'disabilitas',

'pekerjaan',

'alamat'

}

Data Processing and Response, after receiving the data:

Retrieve the User Model data using the email Retrieve the BisaGoUser Model using the User that we previously get Update the name in the User, then save Update the BisaGoUser Model, then save Return response:

{ 'response': 'User updated' }, with the status code 200 (OK)

Error Handling, here are some possible cases that I could think of when creating this API

When the user does not exist in the database, it will return:

{ 'response': 'Internal server error' }, with the status code 500 (Internal Server Error)

When the data that we send is not valid, it will return:

{ 'response': 'User not found' }, with the status code 404 (Not Found)

Usually, after I create this schema, I move on to do the code implementation, don’t forget to use TDD.

TDD? Not again

Yes TDD, or Test-Driven Development. You can see my article here to learn more about TDD. Since we’re using existing data in the database, we have to register the data first. The data that I registered:

{'name': 'Astraykai', 'email':'astraykai@gmail.com', 'password':'chingchenghanji', 'phone_number':'089892218567', 'tanggal_lahir':'1990-05-05', 'jenis_kelamin':'Laki-laki', 'disabilitas':'', 'pekerjaan':'Mahasiswa', 'alamat':'Alamat Palsu'}

Test for when user exist in database and the data that’s sent is valid

Test For When User Does Not Exist in Database

Test For When User Exist in Database, but The Data That’s Sent Is Not Valid

Explanation:

Get the endpoint, in here I use the reverse() method so that I only have to fill in with the endpoint name reverse('update-user') Define the data POST the data to the previously defined endpoint Read the response in JSON format using json.loads() Do assertions

“Is unit testing enough?”

Based on my personal experience, no. Unit testing is not enough. You have to make sure that your API is reachable and return the desired response. You can use an application called Postman to do that stuff.

In conclusion, API is a very powerful ‘gadget’. It reduces the developer’s workload, and it helps them connect to other services without writing a code for it.

Source: