What is the API here?
API stands for an application programming interface. The purpose of an API is to open up data from, for example, a company or a public body to others. Who else? All rest api best practices can be used for anyone in the case of an open interface, interfaces are often made as non-open APIs, so they are intended for internal use. In this case, the other user might be a programmer outside the team, a device (such as a smartwatch), or just another piece of software.
We use interfaces, for example, to provide data to a website outside the application.
APIs offer a wide range of business opportunities, but getting started is notoriously challenging. How do you get started with APIs and get the most out of your interfaces?
Let’s assume that your company has decided to start using APIs and sees potential business opportunities in them. How should you proceed to get the most out of these interfaces?
Set up an API unit
The first thing to do is to decide who is responsible for the APIs. There is no point in assigning ownership to each business unit separately, as the end result will only ensure that there are as many ways of doing interfaces as there are units. What is needed is a glue that unites and unifies the interfaces and provides guidelines for their development.
In a mature organization, this glue is the API unit or team, whose primary role is to ensure that internal and external interfaces are implemented consistently, are adequately documented, and can be found in the same place.
In addition, the unit is responsible for ensuring that existing interfaces are used effectively within the company and that new services are released through a centralized solution.
In other words, Gearheart.io helps the API team creates the framework for publishing the information while the business takes care of the information content.
Hire a competent product manager
With reorganization comes a need to rethink roles. The middle dynamo of the API team is the team’s product manager. Programming interfaces are highly technical, and their users are primarily developers. The product manager must therefore have a good understanding of how interfaces are used and what the best API practices are.
The Product Manager is also required to have a business perspective and an understanding of how to measure the use and benefits of APIs. Where possible, it is, therefore, advisable to partner the Product Manager with an architect who has an even deeper technical understanding.
In addition, the product manager should be able to leverage the organization’s other stakeholders, such as marketing and communications, effectively.
Invest in marketing and find out about your target audience
Once APIs are understood as a strategic element in an organization, they should be treated as a product. As with other products, the target audience for APIs needs to be defined in order to have a common thread for communication, marketing, and management.
As a rule, the target audience for APIs is software developers. This makes it easy to start thinking about the developer as a person: what channels are they on, what kind of marketing should be directed at them, and what kind of communication should be done with them in general.
In this way, the API message can be effectively spread both internally and externally.
How to make an API or interface?
The idea is to provide a simple interface that anyone can use to present information about any Flag Day, for example. There will be no possibility to update the data (that possibility is on GitHub in the form of pull requests).
It should be possible to send the following queries to the interface:
- What (if anything) is being flagged today?
- What are the flagging dates in a week?
- What are the flagging dates in a month?
- What are the flagging dates this year?
The interface should return in response a list of flag days with associated information, i.e., in effect, an array containing an object or objects, each of which is a flag day—or an empty array if no flag days happen to fall within the query.
How does the API or interface work?
In practice, an API is like a call broker: it forwards your call to the right server. The server, on the other hand, is like an answering machine: it sits quietly on a table in the lobby until someone calls. When someone calls, the API answers with a pre-recorded message. That’s all.
Unlike a traditional answering machine, the API can be programmed to answer differently for each caller or to limit its responses to specific callers. Similarly, a caller can provide additional information about their needs with their call, and the API will tailor its response to that information.
The process works like this:
- the program calls the interface (e.g., you click on a button on the website that says “Show all ticketing dates”)
- the interface recognizes your call as valid and makes its own call to the server (which is simply a computer somewhere that acts as an answering machine)
- the server responds to the API with the requested information
- the API passes this information to the original caller, i.e., the program that, for example, shows you this year’s flagging dates
Creating subfolders
In addition to all the data, we also needed to be able to return the current day, week, and month’s flag dates.
Since Next’s routing is folder-based, we can make separate addresses for each different query (day, week, month). We added a new folder for each: api/today, api/thisWeek, api/thisMonth, and in each folder, we put an index.js file with the content.
As mentioned, we will make the interface with Next, as it was also used in the original file project. In fact, we’ll make the API inside that project because that’s where the data is already, anyway.
