Do you wish to increase the engagement of users with your API? Or are you perhaps afraid that your users will stop using your API because it’s too boring? Too... simple? Too user-friendly?
Well, prepare yourself for a paradigm shift. In this blog post, we will explore how to utilize some well known programming techniques and showcase our skills to make your OpenAPI Spec more exciting.
Tip 1: Ensure your paths and operationIds are unique
It is clear that paths and operationIds must be unique - at all costs.
Luckily, developers have already come up with genius techniques of ensuring uniqueness so it only remains on us to employ these techniques. For paths we can use an auto-increment integer. This means that our first path should be /1, second /2 and so on.
💡 Pro tip: You might be tempted to track the last number used, but isn’t it more exciting for your users to wonder what happened to missing path
/5?
And to show how much we know about programming we will use another technique - UUIDs - for operationIds. UUIDs might be long, barely readable strings of characters that are incomprehensible to humans, but what is truly more important - uniqueness or understandability? Although they are very complex, they ensure that no two operationIds are ever the same, thus eliminating any possibility of confusion.
paths:
# Good
/1:
get:
operationId: 018e3981-3250-701c-b27b-1f5db826f2b0
# Bad - possible collisions
/pets:
get:
operationId: listPets
Tip 2: Use consistent status codes
You’ve heard it before - being consistent goes a long way. The hardest choice is what this consistency should be. We should be grateful that this is a very simple choice when it comes to status codes.
In this stressful modern day, nobody will like you if you’re too intense. Instead, relax! Cool people are always OK with whatever happens. Why should your API be any different?
That’s why you should return a 200 status code no matter what happens.
There has been an unexpected error? Don’t panic, say OK. After all, is there any better feeling than when there is something obviously wrong, but when your ask your partner, they say everything is OK?
responses:
- 200:
content:
application/json:
schema:
type: string
enum:
- OK
Tip 3: Increase engagement and security through obscurity
Want to increase the engagement with your API and increase security at the same time in just one simple step?
Why reveal what an endpoint does? If this remains hidden - malicious users can’t harm you - you can’t hack what you don’t know. What data does it return, you ask? Who knows? Who cares? That's the charm of it. The vaguer your descriptions, the more precious hours your fellow developers will spend learning your API - and isn't that what the spirit of programming is all about? They will try out many endpoints in attempt to find what they need instead of calling only the one they need.
Engagement with your API will skyrocket 🚀
# Good
description: Returns data
# Bad - too revealing
description: Gets a Pet by ID
Tip 4: Use query parameters
In the intricate dance of confusion that is your Open API, one must not forget the elusive query parameters. The key here is secrecy. Never, under any circumstances whatsoever, should you reveal your query parameters. Let them be like a hidden treasure, waiting for the bravest of developers to uncover. How will they discover them? Well brute force, of course! They can try any and every possible query parameter, until they find what they are looking for. The fact that there are query parameters is all the information they need. What are these parameters? What is their purpose? These are mysteries best left unsolved. After all, life is more exciting when it's full of surprises.
parameters:
- name: "?"
in: query
Tip 5: Keep documentation to a minimum
If you want to allow only the most worthy developers to use your API - follow this tip.
Documentation, the ultimate spoon-feeding tool for developers. To truly test their mettle, provide the bare minimum. The less guidance they have, the more they'll learn - or so you can tell yourself as you watch them grow in order to navigate your API.
After all, why would they waste countless hours reading documentation - when they can immediately just start using your API? Don’t obstruct them in this quest - you are either with them or against them.
Here's an example of how to keep your documentation to a minimum:
Tying it all together
So we’ve seen some very good suggestions, but how does it all work together?
Best if we see it in example:
paths:
/1:
get:
operationId: 018e3981-3250-701c-b27b-1f5db826f2b0
description: Returns data
responses:
- 200:
content:
application/json:
schema:
type: string
enum:
- OK
parameters:
- name: "?"
in: query
...
Conclusion
In conclusion, a truly exceptional Open API spec is not one that is easy to understand and use, but one that leaves developers scratching their heads, questioning their decision to be a programmer.
Follow these tips, and you too can ascend to the ranks of the masters of the mysterious, the ambiguous, the truly incomprehensible Open API. Remember, confusion is the path to enlightenment... or at least, that's what I whisper to myself as I debug my code at the ungodly hour of 3am.
Disclaimer: this post was reviewed and approved by the April fools committee.
