The beginning is not so RESTful — a first go on building an API
I’ve used API’s for a few frontend projects now, like the Open Weather Map API for my weather app and an API to get and post happy thoughts. In the 24 weeks-Bootcamp I’m attending at Technigo we’re now moving on to building RESTful API’s with Node.js and Express, with one week to finish the first one.
The introduction focused more on the code than the theoretics. To finish on time I buckled up and got going, totally unprepared for the strong feelings involved regarding do’s and don’ts of an API that I was about to discover. Here are the lessons taught during this first go.
Lesson one — the change of user perspective
The 16 projects of frontend I now have behind me has been all about building a webpage that makes sense to the user and let the user interact with it. I think of the user, in this case, as unknown in the sense that it can be anyone. Young old, well educated, not educated at all, unhealthy, healthy and what not. That same user was me, some 17 weeks ago, before embarking on this crazy roller-coaster tour. I know the user by knowing myself, my perception of others and interest in interactions on the web.
Moving to backend, and an API, marked a shift in user perspective. It was no longer anyone, but a particular one wanting a specific thing. Being unaware of this, I started the project with a user in mind that could be just about anyone. My endpoints filled up with greatness, such as /books/toplist (everyone would want a top list, right?) or displaying books written by an author on /authors/:author and so on. I felt like on top of the world, creating one o-so-very-useful-endpoint after another.
Then, as a side note, I presented my o-so-very-useful-endpoints and bright ideas to someone close to me who happened to be specialised in search. And was not prepared for the deep inbreathe followed by dead silence I got as response. There I was, thinking I was doing a service, and instead breaking every rule in the RESTful book.
One reason for this, was me not being clear on the shift in user perspective. The user could no longer be just anyone. It was someone who knew what they wanted, and when they got it could take the reins. My job was giving that data, be precise of what the data was and then — let it go.
Lesson two — what do you expect to get?
Working with book reviews data, it took some twist and turns to understand why books by an author was not a great idea on the endpoint author/:author . Surely, the user wanting data from a book reviews API must be clear on the data being about books and that this is what they’ll get?
The short answer turned out no be — no.
No. Even if books is the theme for the API, nothing in the naming author/:author implies that the data you get will be about books. If books by author is what you give, the user would expect it some place named books.Where would be up to you, but one option would be at authors/:author/books.
No. Don’t make assumptions about what the user think they’ll get. Instead, tell them exactly what they’re getting.
Lesson three — give up control over how data could be used. Or, use a query string
I would never have imagined books/toplist not being a good idea for en endpoint. I mean, there are an endless amount of top lists out there. Surely the user must want one?
Yes, they probably do. But, a top list does not bring any new data to the table. It’s just a way of reordering existing data about books. Since not giving the user a new list of things, or a new item, don’t give them a new endpoint. Instead, build a query string. It could be called /books?sort=toplist , but keeping lesson 2 in mind, it shouldn’t. It’s just not precise enough. If they’ll get /books?sort=average_rating, tell them.
To sum it all up, the third lesson on my first take on building a RESTful API was to give up control on how data could be used and just present what it actually was — nothing more, nothing less.
Luckily, my second take on building an API starts tomorrow. The key learnings I’ll take with me are:
Keeping it to the point.
Don’t make assumptions about what the user might think they’re getting.
Rememeber that the users cannot be just anyone. They are users wanting data and knowing how to use it.
https://book-reviews-express-api.herokuapp.com/ A first take on building an API, by Evelina Berg during the Technigo Bootcamp.
