Posts

The API Handyman writes as time permits

API Design Tips And Tricks - Getting, creating, updating or deleting multiple resources in one API call

Getting, creating, updating or deleting multiple resources in a single API call is a common need in REST APIs. But how to achieve that in a consistent way accomodating how we work with a single resource and REST principles? This is what we’ll see in this post.

Read more

Writing OpenAPI (Swagger) Specification Tutorial - Part 9 - Extending the OpenAPI specification

This is the end, my OpenAPI friends, the end. The end? Not really. This last part of the OpenAPI tutorial is a new beginning. With previous parts we have learned to master the OpenAPI specification but there’s a last thing to learn to unleash its full power: extensions. This format is easily extensible, it allows to add custom data within an API description. But for what purposes? Let’s have a glimpse of these extensions endless possibilities.

Read more

...And GraphQL for all? A few things to think about before blindly dumping REST for GraphQL

GraphQL is new. GraphQL is cool. Look! Github dumped REST for it! We MUST do it too!
Well, why not. GraphQL could be a great tool, but like any tool, you don’t choose it just because. You choose it because it solves a problem in a given context. You choose it knowing its strengths and weaknesses.

While discovering what is GraphQL we will see what REST API providers should think about before blindly dumping REST for it. From design and implementation to pricing model and analytics down to developers experience and implementations, choosing an API design style will have impact on the whole API lifecycle. Therefore, this choice must be an enligthned one and not based on simple beliefs.

Read more

People First: A not so gonzo API Strat Boston 2016 coverage

The last API Strat 2016 day, after the last talk, a man living in kentucky asked me something like What is the one thing you will remember about this conference?. I answered something like People First.

People First. This is definitely what sticks in my mind after this conference.

Read more

Writing OpenAPI (Swagger) Specification Tutorial - Part 8 - Splitting specification file

With previous posts we have learned to produce an OpenAPI specification containing all OpenAPI specification subtleties. Some specification files may become quite large or may contain elements which could be reused in other APIs. Splitting a specification file will help to keep it maintainable by creating smaller files and also help to ensure consistency throughout APIs by sharing common elements.

Read more