Supercharge your API with standards
Our journey into adopting standards for our Sports and Sport Places API
Imagine you’re chilling on your couch, keeping up with the Kardashians 🤢, and suddenly, you come up with the idea 💡 to build an API that will help your peers get the most out of it. Then, you ask yourself:
- Where to start?
- How to get them to adopt it?
- How to make it simple?
These are all valid questions and ones that engineers, product managers and designers ask themselves whenever they’re developing a new application.
And this is exactly where standards come in handy.
Standards in software development are a set of rules everyone agrees on, but also a result of many attempts at solving problems in which developers have struggled for ages.
When standards are adopted, especially in open-source software, the community wins. But you may be tempted not to and ask yourself: why? what if I want to model my data in a way that works best for my business?
Well, throughout this post, I’ll try to convince you otherwise and appreciate the beauty of standards. Please bear with me here. :)
Where to start?
Before we start looking for a standard to model our data after, we need to ask ourselves: What kind of data am I trying to display?
Take our Sport Places API as an example; as the name itself describes, the goal of this API is to display locations where you can practice sports, to do so, we thought it’d make sense to display the data as a set of coordinates and attributes that could easily be loaded into a map; therefore we decided to adopt GeoJSON as our standard. Below you can see an example of GeoJSON in action:
{
"type": "Feature",
"properties": {
"uuid": "8b1e3027-e438-42c2-92ab-5ebd23f68d54",
"name": "McConnell Arena",
"google_place_id": "ChIJ5XD-5zAayUwRIK7t7t89ZJ0",
"contact_details": {
...
},
"address_components": {
"address": "3883 Rue University",
"city": "Montréal",
"province": "Québec",
"country": "CA"
},
"activities": [
{
"sport_id": 160,
"tags": [],
"difficulty": 2,
"distance": 10
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-73.5826985,
45.5119864
]
}
}Recently I had to develop another micro service that would ultimately become the Sports API; An AI-Powered sports recommendation engine for all sport tech entrepreneurs. p
We figured it’d be appropriate to adopt the JSON:API standard, as it is the de-facto standard specification for building APIs with JSON.
{
"data": {
"id": 175,
"type": "sport",
"attributes": {
"name": "Ice hockey",
"description": null,
"parent_id": 404,
"decathlon_id": 175,
"slug": "ice-hockey",
"locale": "en"
},
"relationships": {
"children": {
"data": []
},
"parent": {
"data": {
"id": 404,
"type": "sport"
}
},
"tags": {
"data": ""
}
}
}There are many other standards out there that are definitely worth checking out:
How to get people on board?
Getting people to use your stuff is always the hardest part. One of the most common reasons is that, perhaps users already have a legacy system where making updates is hard, or not worth the trouble.
This is where using a standard comes out ahead. When a standard is adopted by an organization, it follows the same structure across the board, making content migrations and systems integrations a lot easier.
In fact, using a standard format might even be a marketable tool towards your project. Developers are usually fond of things that just work and don’t try to reinvent the wheel.
Successful examples of this approach are Stripe’s API, Twitter API, Google’s APIs amongst others.
* All of the above examples have adopted either the JSON:API/Schema or GraphQL.
How to make it simple?
If you ever played around with Stripe’s API, the first thing you’d have noticed is how simple everything seems and how seamless it looks across the board.
One of the reasons, besides Stripe’s amazing effort into delivering beautiful documentation, is the fact that the response and the request formats look similar across multiple services.
That makes it trivial to navigate between multiple APIs and to write integrations between them.
One more thing, tooling
While most tools are capable of parsing serialized data acceptably well, some excel at interacting with well-formatted objects. Google Maps API for example will automagically load a GeoJSON object when it finds one, eliminating the need for, perhaps dozens of lines of code into your application.
If you work with APIs on a daily basis, you’re probably using a tool like Postman to perform calls and run tests against them. Postman tests can be made re-usable when following a standard format such as JSON:API.
Summary
Make sure your APIs are following basic guidelines that have been in use by the software development community for years. That will make your life, your team’s life and other people’s lives a heck of a lot easier in the long run.
Feel free to comment below if you have a different point of view or additional suggestions, or if you’d like to learn more about how we structure our applications here at Decathlon.
Or if you feel like you can help us improve upon our standards implementation, come join our team: https://developers.decathlon.com/careers
