Web APIs explained
Forward: This article is meant to help readers understand the basic technical aspects of modern web APIs.The following analogy is a simplified version of how databases and APIs work, and a substantial amount of information has been omitted to achieve this. Co-Authored by Ian Johnson
The magic of the modern web
If you’ve been on the internet in the last decade, you have almost certainly used a web app at some point. At their core, a web app is just a web page that allows users to load, manipulate, and save data in some way. Take Twitter for example. When you go to the Twitter website and login, it loads tweets from people you follow, and you can compose and send your own tweets for your followers to read.
But where did those tweets come from? Where did your tweet go when you sent it? The answer, in most cases, is a web server. The web app sends a request to the server for tweets, and the server responds with the requested data. The same goes for sending your tweet. The app sends the tweet to the server and it handles saving it and notifying your followers.
However, this raises more questions like: how did the server know what tweets to send and how did the programmers know what to put in the request for the tweets? These questions are the reason software engineers create Application Programming Interfaces, or APIs.
WHAT IS A WEB API?
In the simplest sense, an API is any code in a software system that allows other software systems to interact with it. A Web API is just an API that allows other systems to interact with it via the Internet. While a Web API can have many different functions, the most common functions involve manipulating data using the four operations found in the acronym “CRUD”:
- Create new data
- Read existing data
- Update existing data
- Delete existing data
These so-called CRUD operations are found in nearly all applications. After all, Twitter wouldn’t be very useful if it didn’t save your tweet in some way so that others could read it later. While there are several different ways to store data, one of the most popular is the relational database. To better understand APIs, let’s first take a look at how databases work.
File cabinets, mailboxes, and workers
A relational database is simply a way to store data in an organized fashion. You can think of it as a big file room where information is stored in a collection of file cabinets. Each file cabinet has a form associated with it, which describes how data stored in the cabinet is structured. This form has different fields each of which stores a specific type of data.
When a new form is filled out and stored, it becomes a record. All this work is handled by a file room worker.
For example, let’s say we have a company that sells books. They provide a list of books that they sell and take orders from customers. They could have three file cabinets, one for Books, one forCustomers, and one for Orders. The Books cabinet would have a form with the fields ID, Title, Author, Genre, and Quantity Available. The ID field is an arbitrary unique identifier for the record, normally a sequential number. When the company receives a new book in stock, they would create a Book form with the title, author, genre, and quantity available, and insert it into the Books file cabinet. If someone wanted to know how many copies of “The Great Gatsby” were in stock, they would select the record in the Books cabinet where the Title is “TheGreat Gatsby” and read the QuantityAvailable field.
One of the types of data that can be stored in a field is a relation. Relations allow a record to reference a record in a different file cabinet, allowing the file room worker to quickly find the referenced record. Relations also prevent duplication of data and maintain consistency when multiple records reference a single record. For example, instead of each Order record having all the customer data in it, the Order form would just have a relation to theCustomer file cabinet record that contains the customer’s information.
All this information is stored in a master diagram that describes everything about the file room. The file cabinets, forms, relations, etc. are all stored here and can be read just like a normal record.
The file room worker
All these operations are performed by the file room worker. Any time a record is being read or created the worker is the one that is doing it. In order to get information from the file room, a user needs to ask the file worker to get the data for them.The worker is incredibly good at their job, but they are quite particular about how you speak to them. They only understand specific requests written in an arcane language. While the arcane language is extremely powerful when spoken correctly, it is complex, verbose, and can be difficult to write at times. The more specific the information you want, the more complex the request becomes.
The great thing is that because this worker is a computer, they are blazingly fast.They can find, retrieve, and edit millions of records in seconds, all while ensuring that they don’t mix up records or lose any data. The file worker also keeps track of changes to the file room, recording every new file cabinet in the room or field in a form in the master diagram. These are the advantages that speaking the arcane language skillfully provides.
Now that we understand databases, let’s look at how APIs allow access to them.
The mailroom, mailbox, and mailroom workers
To represent the API in our analogy, imagine a mailroom with a big mailbox, and workers. These workers open and read requests sent to the mailbox. A user sends a request addressed to the mailbox in the mailroom. The request is written in a simple language that is much easier to write than the arcane language of the file room worker.This language makes it easy to describe what information the user wants to retrieve or modify. The mailbox workers have been trained to translate the easy language into the arcane language and then forward the translated message to the file room worker. Before doing so they also check that the sender of the request can access the information described in the request. If they are not, they reject the request and notify the sender that they can’t do that.
After sending the message to the file room worker, the mail worker waits for a response. Once they receive a response, the mail worker has two options; they can send the data directly to the sender, or they may make some additional changes to the data first before sending. This decision is made based on how they are trained to handle each request.
An example request may look something like this. A user sends a message in the easy language that says, “I would like to order 1 copy of ‘Harry Potter and the Goblet of Fire’. Signed - Alice”. The mailroom worker first ensures the senders signature matches the one they have on record for Alice. Then they translate the message into “Fill out form Order with the following values: the time is the current time, the customer identification is a reference to a customer with the name “Alice”, the book identification is a reference to the book with a title of“Harry Potter and the Goblet of Fire”,and the quantity is one.”
This message would then be sent to the file room worker, who would quickly perform the requested action and respond with “Added 1 record.” The mail room worker would then respond back to the sender with “Your order has been processed. Thank you and have a nice day!”, and the process is complete.
An important note is that the mail worker needs to be trained for every possible request. The information put into the request can vary, but they need to be trained how to create a book, how update the title of a book, how to delete a book, etc. If they receive a request they weren’t trained for, they respond to the sender with an error saying they didn’t understand the request. This means that a large file room with dozens or even hundreds of file cabinets could have thousands of different requests that it can receive, each one requiring specific training for the mail worker.
Training mailroom workers
Now that we understand how the process works, it is clear that the hard part is training the workers to perform the translation of the simple language into the arcane language. In traditional development, training the workers is what software engineers spend a substantial portion of their time doing. This takes hundreds, sometimes thousands of hours or more for a single application. Developers look at the master diagram of the database and then train the workers on how to properly write requests for the file room worker.
Enter Devii
Since the master diagram is already there, isn’t there a way to have the mail workers read it and train themselves? There is! This is exactly what Devii does. It looks at the master diagram and figures out how to translate the file cabinets, forms, and relations of the file room into different words that make up the simple language. It also knows how to interpret security policies and train mail room workers to only allow access to data the user is authorized to view. Instead of the hundreds of hours that engineers would spend training the mail workers, Devii does the same work in just a few minutes.
Exiting our analogy, engineers write code that translates simple request messages into SQL queries that the database understands. Each of the CRUD operations needs a unique function written for each table of the database.
Devii introspects the schema of a database and builds the GraphQL resolvers that engineers would normally write manually. It does this in a way that allows the application of security policies to prevent unauthorized users from accessing or altering data they are not supposed to.
Summary
Applications need to store information. This is commonly done with relational databases. Communicating directly with databases is unfeasible for reasons including security, performance, ande ease of use. Web APIs are used to allow access to databases while retaining control of what information is accessible.Traditional API development takes hundreds to thousands of hours to develop for each application.
Devii automates a substantial portion of that development time by utilizing the structure of the database found in the schema. It combines this with security policy rules defined by engineers to generate a GraphQL API that offers secure access to the database.
Limited Offer.
