#5: Three principles of API design that you should focus on
Three principles of API design that you should focus your team on
On my career path, I saw a lot of different kinds of APIs: SOAP / REST / GraphQL / gRPC… I believe API Design is one of the most influential parts of your product that drastically impact your delivery and success of the result. Here I’ve got 3 key considerations regarding API design for you.
Design for USAGE
If you develop your project’s API in a code-first approach, there is a temptation to make it friendly for developers who work with this code. Unintentionally break compatibility because there is some legacy and easier to remove/refactor than maintain. The problem is that API shouldn’t serve the need of your team but rather another one or the need of your clients, but definitely not the API author's interests first. Try the schema-first approach to think more about “how the customer sees this api”.
Move the API schema to another repository.
If you have well-known consumers, ask them to review changes in the API.
Design the API to make it consistent, predictable, user-centric, and simple for the consumer but not necessarily simple for a creator.
Design for EVOLUTION
What will happen with your API in one year? You probably don’t know because changes come so quickly nowadays. So the single thing that you might be sure 100% is the fact of future changes. Then why should you not take that fact into account?
Think about the following things:
If we needed to redesign API in a few months fully, how would we version it?
If we needed to remove this field from that object, would we need to expose it now?
If we didn’t make this design decision now, would that really impact us in the future or not?
If we made this design decision, how expensive that would be to change later?
Design for PROTECTION
Obviously, API is not just fancy client-focused stuff. Consumers might be divided into two cohorts: those who just want to use our API to solve their problems and those who try to exploit/challenge our API to get some unfair advantages or just to satisfy their curiosity. “Design for USAGE” section was focused on the first cohort, so let’s talk about the second one.
How to design for protection?
Minimize attack surface, do not expose more than needed
Separate concerns:
private and reach API for your team.
internal API for other systems in your company.
public API for the Internet and third parties.
administrative API to manage your app.
Test API (and app dependencies) with the standard security scanners.
Prepare for DDoS if you expose public API (just use standard services like Cloudflare).
Use standard protocols like OIDC and SAML, do not reinvent the wheel.
Permit nothing by default and carefully unlock permissions for particular users.
Conclusion
API design is a vital part of software development, and it requires a ton of attention. It is the first thing I personally review in every Merge Request, and I recommend you do the same. I hope these three principles will help you move more consistently on your road.