Application Programming Interface (API)

I will try to explain what is API in a way that you can imagine. Hopefully, you can relate it to whatever digital cloud-based products you are currently working on.

Courtesy of unDraw - Server status

Client, Server, and API are the first 3 words I often heard in my workplace earlier in my career journey, and it sounded alien to my ears as I just graduated from Environmental Economics study. Knowing these terms really helped me communicate better with the Tech team and navigate the world of software development in general. As for API specifically, knowing what it is and how it works, helped me think what the required tasks and efforts the team will perform to deliver certain functionality.

The way I understand 'API' might not be as accurate as what is understood by our engineering friends. But hopefully, it could give you an additional information about this topic, especially for you aspiring PMs who are not coming from technical background like myself.

The good news is, I will show you real-life example of what kind of API I often encounter and what benefits you will gain from knowing this that will help your day-to-day works as PMs.

Client-Server-API

Let me borrow the definitions of the three terms mentioned above from RapidApi's glossary:

• Client-side refers to the operations and tasks that are performed by the client when it comes to the client-server relationship in the computer network. When it comes to web development, client-side scripts and programs are embedded in the client’s web page and processed on the browser.

  • I often assume Client as the computer system that is directly used by the end users (e.g. browser, smartphone apps, personal computer softwares).

• In a nutshell, when something is on the Server-side, we basically mean that it is or will be executed in the server or a remote machine, or in the cloud where permanent databases and files are stored.

  • I often assume Server as the business logic and functionality programmed in the cloud that will serve and process any request from the Client.

• Meanwhile, API is an acronym for Application Programming Interface, is a set of definitions and protocols that allow technology products and services to communicate with each other via the internet.

  • I often assume API as the bridge or gateway or mediator between Server and Client, so both can communicate with each other.

The picture above told us the commonly used analogy of ordering food in a restaurant to simplify how API works: YOU as the user, MENU as the client-side (and your voice), Placed ORDER as the input for the API, WAITER as the API protocol itself, KITCHEN as the server-side, and Processed ORDER as the output from the API. Also, as mentioned in the picture, in some cases server-side could not return what client is looking for (e.g. data not found, invalid credentials, and system error).

About REST APIs

REST (Representational State Transfer) is one of the most popular API styles used worldwide. Now another borrowed explanation from techtarget:

A REST API is an architectural style for an application program interface that uses HTTP (Hypertext Transfer Protocol) requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting (CRUD) of operations concerning resources.

Any REST API will have API endpoint(s), it is a point at which an application program interface -- the code that allows two software programs to communicate with each other -- connects with the software program. APIs work by sending requests for information from a web application or web server and receiving a response.

I do not really understand the meaning of REST and even HTTP, technically. But one thing you need to know that REST is using HTTP as its architectural style, while HTTP itself is designed as a protocol so that client and server could establish communication. I think you should familiar with this: when you try accessing a website, the 'http://' prefix will be automatically added to the website's domain, it means the browser is using HTTP to establish communication with the website's server you are targeting.

I still remember, CRUD was also one of the most frequent terms I heard in the workplace when talking about API. Before I show you an example of API, let's discuss a little bit of each of the operation command mentioned above, as per my understanding.

• Create: an operation or command when you are telling the computer to input or insert new record to database such as insert new user's profile, insert new product, insert new category, or insert new bank account.

• Read: an operation or command when you are telling the computer to retrieve the data you have inserted before. In this case so that you can re-read the data such as user's name or bank account number.

• Update: an operation or command when you are telling the computer to update certain or all information that have been inserted to the database previously. Such as updating the user's photo profile, user's email address, or user's date of birth.

• Delete: an operation or command when you are telling the computer to delete all or partial data or record that has been stored in the database. It could be permanent/hard delete, or soft delete (flagging a record as "Trash" but still keep it inside the database).

Example: Register API

I've been working on more than 15 digital products and almost all of them have this Register Feature. What makes a difference among them is mostly because each product had certain User Experience (UX) they want to offer. But technically, from my experience, the method to communicate between client and server should not differ too much. Now, let's get more technical!

Supposed you work as a PM at the early stage startup to build its MVP app version. One of your earliest tasks is to develop the App's Register feature, after discussing the user flow with the team, you probably come up with this user story (requirement):

As A User, I want to be able to register an Account using my Phone Number, so that I can log in to the App.

User Flow: Users Input Number > Users Get SMS OTP > Users Input OTP > Register Success

The Design team will then translate the requirement into workable UI design, such as the one shown in the picture above. The Frontend team will implement the UI screens on the client-side while the Backend team will implement the registration logic on the server-side. Backend team will also provide the Register API to be integrated by Frontend team, once the UI screens have been implemented. Sounds easy right? But what actually happen behind the screens? Actually, Backend team will provide several API endpoints, according to user flow mentioned above.

Request SMS OTP

POST https://api-dummy.com/v1/otp/request

Firstly, when users type in their phone number in the textfield and then trigger the "Register" button, client-side will call an API endpoint to send that phone number to server-side, so that the programmed logic can send OTP via SMS to that particular phone number.

Request Body

Name	Type	Description
Phone Number	string	"081234567890"

200

{
    "meta": {
        "code": 200,
        "status": true,
        "message": "Success"
    },
    "data": {
        "detail": {
            "seconds_to_expire": 120,
            "success": true,
            "otp": 9126
        }
    },
    "error": null
}

Every API call will be consisted of Request and Response. Referring back to the restaurant analogy, Request is the Placed ORDER that you tell API to relay to the server-side (input), while Response is the Processed ORDER that the API got from server for client-side to consume (output). Please also notice that here we are using "POST" method because it's an Insert or Create new record command/operation (a.k.a registering new user).

In this case, the request has 1 body parameter that is the phone number input by users. As for the response's parameter, it could be a success or a failure that can be seen on "meta" > "status" field. In above example, the response is true. So, technically the users will get the SMS OTP of 9126, please refer to response's parameter: "data" > "detail" > "otp" field.

Register New User

POST https://api-dummy.com/v1/user/register

Once users get the SMS OTP, they could input the OTP code into the registration form and then trigger "Verify" button. The client-side will then call an API endpoint to pass the request parameters to the server-side, to verify whether it's a valid request or not.

Request Body

Name	Type	Description
Phone Number	string	"081234567890"
OTP Code	string	"9126"

200

{
    "meta": {
        "code": 200,
        "status": true,
        "message": "Success"
    },
    "data": {
        "detail": {
            "id": "Okad924sf",
            "phone_number": "081234567890".
            "full_name": "",
            "username": "",
            "email": "",
            "type": "user",
            "image": "/image-user/SJKFskf92.png",
            "is_active": true,
            "access_token": "kKSksKJF92FCadsk03j0q3rksfsSafNK",
            "token_type": "Bearer",
            "refresh_token": "kadsjfksdjgsdlkKAJDksjf92r09SDK",
            "expires_in": 360000,
            "created_at": 1589439163,
            "updated_at": 1621269696,
            "deleted_at": null
        }
    },
    "error": null
}

400

{
    "meta": {
        "code": 400,
        "status": false,
        "message": "Invalid OTP code"
    },
    "data": null,
    "error": null
}

Same with previous example, but now the request's parameters consist of Phone Number and its recently input OTP Code fields. When the server-side's programmed logic found out the combination to be true, it will return a success response and the account is created. In contrast, if it turned to be false, the API will return a response with error message such as "Invalid OTP Code" thus the account is failed to create. Users should retry the process.

Conclusion

After reading through the whole article, you should now aware that there are several tasks need to be initiated and implemented behind the screens, even for this simple Register API module. Not to mention, we haven't discussed negative scenarios such as trigger resend OTP code, phone number is already registered, and forgot phone number.

Hopefully, you can start analysing the API products you are currently working on, because it will benefit you in some ways:

• Estimate the task efforts more accurate, as you can imagine how actually the backend and frontend team will probably solve the functional requirements. Up to the point that you are able to list down all the major steps your team will likely to pick.

• Test early version of the API endpoint even before handing it over to frontend team. You can act as the gatekeeper to make sure that the business logic have been implemented well according to your requirement. This will save you time and avoid trouble.

Thanks for staying until the end. Next writing, I will be discussing about how to create a User Flow with context and example.