UI/UX designer's guide to APIs
The “API” is used so often in conversations lately, that it can feel daunting when you think you don’t know what it means and how it can be used. Every tech company provides APIs to access their public data. Facebook, Google Maps, Spotify, Twitter, and Instagram, all of them have APIs that can be used to build apps and websites. But what these APIs are might be a mystery to a lot of people.
API stands for Application Programming Interface. Similar to UI (User interface) being an interface for Users, API is an interface for developers to do the same things users do through the UI. Just like a UI, it guides users into doing things the application can handle.
It all boils down to the fact that you want to run a program that you have (web application). One of the main characteristics of web programs is that they run continuously and wait for a user to ask something (make a web request) and give a corresponding response. Ultimately, an API of a web application is a means to do that request. It limits and guides the user on what she can and cannot do using this application.
Suppose your application does one thing. It prints “Hello World” every time a button is clicked. Let’s look at what happens under the hood when a button is clicked in a side-by-side view of UI events and the corresponding API requests. In the following set of gifs, simple UI animations are shown alongside corresponding API requests and responses at the bottom.
The brackets around the “Hello World” text and “message” are just part of one of the formats API can return data in. For now, let’s just leave it at that. Also, it suffices to say, that the GET keyword means that we want to get something from the web app. There can be other keywords that API might support and we will look into those later.
Now let’s say the developers added a new feature to our application. It can now take some input and change the behavior based on that.
Now it allows you to input your name and it would print “Hello {your name}!”. On UI you get a text input field along with the “Show” button, as shown in the gif.
The q=Hafiz is a means to send parameters to the API. In this case, we use it to send the text Hafiz
At this point our API supports the following requests:
GET /hello-world
GET /hello?q={name}Now let our application do something more; instead of a simple hello world, we want our application to be able to create greetings and list them as a history. Also, it would allow doing some basic filtering. For this, we would have two views for each of these features.
First, let’s look into listing those greetings.
Next, let’s look at how our API to filter the list would look like together with the UI.
On the UI we now have an additional input text field. We will use a query parameter qto send the text we’d like the list to be filtered by. Query parameters are part of the URL and come after the ?symbol. In this case, ironically it is called q which is just short for “query”. Its value is Haf. The result is still a list with the items filtered out according to our query parameter value.
Next, let’s see how we would go about the creation of a new greeting. From a UI point of view, we want to have a view where we enter the name we want to greet and then view the created greeting in the next one.
Our API for this would look similar to the following snippet:
Request:POST /greetings
{
"name": "Kim"
}Response:
{
"greeting": "Hello Kim!",
"date_created": "01.01.17"
}
As opposed to previous requests, creating a greeting requires us to make a POST request to /greetings. Just as GET means to get something from the app, POST represents posting something to the web app with the idea that it will be saved somewhere for later reference. A POST request would usually have a body where the parameters of the request are put. The body is usually in the same format as the response.
There are some more “verbs” that could be used in the design of an API. These are part of a communication protocol called Hypertext Transfer Protocol (HTTP). DELETE for example, would be used to represent the deletion of something. These are the most commonly used ones and therefore enough to know about for now.
With the addition of these features now our API consists of the following endpoints:
GET /hello-world
GET /hello/{name}
GET /greetings //get list of greetings
GET /greetings?q={text} //get greetings filtered by input text
POST /greetings //create a new greetingSuppose we decide that we want to greet our users with more sophisticated wording than just “Hello”. For this, we think of delegating the logic of choosing the right text to another application. Here is what this application does:
- Generate a greeting text according to the time of the day (e.g. Good Morning, Good afternoon, Good evening, Good night, or simply Hello).
- A specific date and time could be sent as input and the resulting text would be generated according to that time.
Here is what an API for such an app could look like:
GET /greeting-texts
GET /greeting-texts/{timestamp}Some example requests and responses to this API would then look as follows:
So now, using this new API, we can improve the creation of new greetings in our greetings app. Whenever our API gets a POST /greetings request, it first makes aGET /greeting-texts request and uses the resulting text to create our greeting. Let’s look at our last example with POST.
POST /greetings:{
"name": "Kim"
}
Under the hood the greetings app requests GET /greeting-texts and gets “Good afternoon” and the formatted date “03 Jan 2017”. The result would look like this:
{
"greeting": "Good afternoon, Kim!",
"date": "03 Jan, 2017"
}These examples are a bit simplified. Real-world APIs have more details, like security parameters and status codes to know if our request was successful or wrong, etc. But the essence is quite simple.
In future articles maybe we can go through some of those real APIs.
