TwosWrite things down

What is an API? - APIs for dummies

What is an API? - APIs for dummies

by trobo · 55 things on Twos

This is a quick explanation so you can understand APIs even without any programming knowledge.
APIs are very common in application programming
The acronym API stands for
Application Programming Interface
By definition, it is "a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service."
Essentially, it is a way to ensure communication between two pieces of software, so it is crucial for a lot of things like connections to a mobile app.
---
How does Twos make use of APIs?
Twos uses APIs to connect the web and mobile apps to the server which manages all data and stores it in a database in the cloud
Like most modern APIs, the Twos API uses some standards like HTTP and REST to simplify the process of creating, managing and using/consuming the API
Explained in a simplified fashion, HTTP is the protocol used to transfer data through the Internet using special messages, also known as requests
Examples are:
the GET request which fetches data from a server (e.g. accessing TwosApp.com is essentially just a GET request fetching all the needed files to display the website)
the POST request which sends data to a server to then be further processed
REST is a convention/architecture style for standardizing how APIs should be built and accessed
---
Concrete example in action:
The user pushes a thing to their today list from the web app
The content of that thing is "test"
To send the data over to the server to process and store it, the web app makes a POST request to the correct address on the server, to let it know where the data needs to go and how it has to be processed
In this case, the POST request will be made to:
https://www.twosapp.com/apiV2/user/addToToday
As we've learned before, the POST request needs some data to send to the server.
In programming terms, this is also called the payload.
Our payload for REST APIs is usually a special format called JSON
JSON is a way to represent data in pairs of key and value like key: value
For example: "myUsername": "trobo"
Or "thingText": "test"
This is how our payload would look for pushing a thing to today in Twos:
(Image credits go to user gijs.epping)
Here we can see the text key, which has the value of the thing we want to add to our today list
Title is the name of the list we are adding to, which us our today list
User_id is a special identifier for your account
Token is a special string of characters used to verify your identity (making sure that you are actually the user the user_id belongs to and that you have permissions to edit the list you are trying to edit)
Now the POST request including the data we have sent in the payload arrives on the server (a remote computer running all the things for the API)
Here, it is being processed and finally sent to be stored in a database.
That's it! Our thing has now been stored so it is sitting in your account's today list. It is persistently stored so we can see the thing even after refreshing the page or even accessing it from another device 😲
That's how an API works and magically allows communication between our local app (client) and the remote computer (server) which is responsible for processing, managing and storing our data.
Keep in mind that this is a simplified example and it might not be 100% technically accurate.
Now what's the catch?
Our little "problem" in the case of the Twos API (or some others too) would be that the addresses which point to the correct "locations" on our server are not publicly available.
We know that for our example we need to access twosapp.com/apiv2/user/addtododay, but what if we want to do something else now?
We would need to know what address to use for an action like adding a thing to a random list.
In this case, there is no documentation/manual, so we can only guess the address or intercept the app when it is sending these API requests.
For apps that do want to keep their API away from tinkerers building 3rd party clients or bots with potentially malicious intent, not publishing the exact "routes" (the exact addresses of every action their API can do, like adding a thing, sending data, editing profile information) makes sense.
This concept is called "security through obscurity" - securing your system by hiding internal details.
While this is a good initial layer of security, usually there are more security measures in place to make sure an API cannot be abused.
To allow developers and tinkerers to make use of the API and do cool things like automation with Zapier, most apps provide public APIs with documentation on how to use them and some restrictions to prevent abuse but still allow a certain level of flexibility.
This is what I'm hoping to see for the Twos API at some point (and it has been put on the roadmap by Parker) ✌️
Hopefully this list is helpful to anyone who wants to understand what an API is and how it works.
If you found this helpful, feel free to leave a tip 😉
Happy Twosday!