Win a copy of TensorFlow 2.0 in Action this week in the Artificial Intelligence and Machine Learning forum!

Arnaud Lauret

Author
+ Follow
since Dec 27, 2019
Cows and Likes
Cows
Total received
0
In last 30 days
0
Total given
0
Likes
Total received
7
Received in last 30 days
0
Total given
1
Given in last 30 days
0
Forums and Threads
Scavenger Hunt
expand Ranch Hand Scavenger Hunt
expand Greenhorn Scavenger Hunt

Recent posts by Arnaud Lauret

Indeed, API Portals providing API documentation are valuable, even for private APIs. Without them nobody is aware that APIs exist. Some API management solutions may provide API portals, they may be OK for private APIs, but when it comes to public ones, there is usually some work to achieve something good. It may be better sometimes to start from scratch. Also when you want to provide API documentation for APIs that do not exist yet, you may have to do some modifications yourself, these out of the box solutions usually do not handle such case.
9 months ago
Thank Ludoviko for the quote, indeed the book focus on design, talking about all tools to use along the API lifecycle would need another book. But I still can give you some insight about what I use.

To design APIs, I write plain OpenAPI Specification files either using Swagger Editor (https://github.com/swagger-api/swagger-editor) or VS Code with some extensions (https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer and https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint). If you're not into writing YAML, I recommend Stoplight Studio (https://github.com/stoplightio/studio).

If I need to run a mock of a design to see how it feels to use it, I use Stoplight Prism (https://github.com/stoplightio/prism)

When it comes to testing I recommend to do as much as you can low level unit testing (with your favorite tool) before mingling with the HTTP level with tools such as Postman or even the good old SoapUI and also ReadyAPI (from Smartbear).
9 months ago
Based on my personal experience, design has been most of the time neglected in favor of quick coding. But slowly but surely, things are changing thanks to public APIs offering awesome developer experience with good design and documentation, people start to realize that spending a moment on design (even for private APIs) before actually coding is worth the (very small) overhead. When you balance "a few hours of design" vs "days of hellish web services/apis integrations" (and I do not speak of design evolutions, security flaws, APIs at scale, ...), the choice is easy to make.

Established APIs (such as Twilio or Stripes for example) are usually well designed because if they are not, people do not use them and the companies die. There still be may some that are not that "good" (based on my standards) nowadays (like the AWS APIs or Saleforces ones as far as I remember) but they are still usable and as the providing service has almost no match, they will probably not change. That's for public APIs.

But when it comes to COTS (you know good old corporate software you install on premise), I have never ever seen any COTS company taking care about their APIs, the ones I have seen have always been a total nightmare.
9 months ago
All readers I met actually find it useful :-)
9 months ago
Hi,

The book describes some best practices regarding needs analysis and decomposition, HTTP API design, errors handling, versioning and security and even more.
Can you be more specific about what you're looking for?

Arnaud
9 months ago
Hi,

Versioning is discussed in version 9 which talk about evolving API design and covers:

- Designing evolutions to avoid breaking changes
- Versioning APIs to manage breaking changes -> this is what you are looking for (different technics, pros and cons)
- Designing extensible APIs to limit breaking changes

Arnaud
9 months ago
Hi,

Already answered that question : "Though focusing on REST as a main example, The Design of Web APIs aims to teach design principles that you can use for any type of APIs. Most of the principles you will find in my book can be applied to GraphQL APIs but you will have to do some work on your side to apply them on this API style." (see this thread: https://coderanch.com/t/725654/java/Design-Web-APIs-practices-GraphQL)

Arnaud
9 months ago
Ah ok. Indeed, GraphQL queries can be verbose because you have to state exactly what you want. The big challenge regarding GraphQL API design is consistency as there is no frame (such as the HTTP protocol uniform interface) to design an API consistent with itself and consistent with others.

Another warning about GraphQL (or any other type of API): did you actually choose to use this specific type because it is the best solution in your context or did you choose it because of "hype/we always do that/any other groundless reason"? It is really important to choose the type of API based on the context and the needs and not belief or habits.

I recommend watch Zdened Nemec amazing talk about "how to choose an API style": https://www.youtube.com/watch?v=gRZbgsmDj_0
9 months ago
There are 2 that I'll never forget:

- The first one was designing an API in french (get /├ęcureuils instead of get /squirrels). As I later introduced design concepts coming from Hydra that were in english, I ended with a totally awkward "frenglish" API (It was the topic of my first post on my blog http://apihandyman.io/why-you-must-design-your-private-api-in-english/).
- The second one was to focus too much on the resources or the data should I say (/customers or /accounts) and totally set aside the use cases that needed to be fulfilled by the API. It resulted in a very fine grained API needing to endlessly do the 5 same APIs calls to do a simple thing. That's why I in the book I focus on analyzing the needs BEFORE designing data models :-)

Regarding the second part of the question "how to overcome these mistakes", these 2 mistake represents 2 types of design problems.

- The first one, the french design, is the perfect example of shitty-design-you-have-to-live-with. Indeed, while not as good as it should have been ,this design was doing the job and as the API was already consumed, it was too late to change it because it would have been a breaking change for consumers. We had to wait some opportunity like introducing totally awesome new features to make the move to a v2 full of breaking changes worth the cost for consumers.
- The second one (design not fulfilling needs efficiently) was solved by adding a new operation doing what was really expected inside the existing API (without introducing any breaking change). As it was a pain-in-the-ass solver, consumers were happy to make the change (to avoid doing the same 5 API calls). And ff some of them don't want to do it they could still use the original operations.
9 months ago
Hi,

Though focusing on REST as a main example, The Design of Web APIs aims to teach design principles that you can use for any type of APIs. Most of the principles you will find in my book can be applied to GraphQL APIs but you will have to do some work on your side to apply them on this API style.
And why talking about "chatty GraphQL", wasn't GraphQL supposed to solved the "chatty REST APIs"  problems? ;-)

Arnaud
9 months ago
Hi,

The Design of Web APIs focus on the design of interface contracts not they are actually implemented, therefore  I do not talk about frameworks. By the way Apigee is not a framework, it is an API gateway solution. The main purposes of an API gateway are vitualization, security and logging and absolutely NOT implementation. Do not listen to API gateways vendors if they tell you that you can put API implementation in their gateways :-).

Arnaud
9 months ago
Hi,

There is no open source or commercial tools to actually design APIs (I should say: no tool that meet my expectations :-) and providing all the features needed to do what I describe in my book). But there are open source tools that you can use to describe your APIs taking advantage of the OpenAPI Specification. If you're into learning the OpenAPI Spec and writing YAML, you can use the good old Swagger UI (https://github.com/swagger-api/swagger-ui). There is also Stoplight Studio (https://github.com/stoplightio/studio) which let you describe your APIs (generating OpenAPI code under the hood) without having to write a single line of YAML.

Arnaud
9 months ago
Hi,

In this book, I describe how to use the OpenAPI specification to design (chapter 4) and document the API (chapter 12) but I do not dive more in how to extensively take advantage of it (code generation, tool configuration, linting, ...) , that is not the purpose of the book which is focusing solely on design. If you want to dive more into this topic maybe you can look at this book https://www.manning.com/books/designing-apis-with-swagger-and-openapi (it does not cover all topics though)

Arnaud

9 months ago
Hello everyone!
Happy to be there, I look forward to your questions about API design.
9 months ago