Secrets to Great API Design (2019)(nylas.com) |
Secrets to Great API Design (2019)(nylas.com) |
Comments were very insightful as always. I kind of agree with OP, this article is very thin on content and mostly peripheral take on good API design. It is unhelpful.
Don't add GraphQL without understanding what you're getting into. I wouldn't use it in the same 'latest frictionless' context that the article mentions.
I also like "self-eating dogfood" in that the shortcuts are defined using existing "long-cuts" and the API user can study, learn from, and change and/or write their own shortcuts using the long-cuts.
C#'s optional-named-parameters (ONP) are ideal for such. I don't why Java and JavaScript don't implement ONP's. The alternatives, such as object literals and method overloading, are just too clunky. Once you tasted ONP's you don't wanna go back.
How to Design Better APIs | https://news.ycombinator.com/item?id=30647784
I see what did there
TLDR;
1. Shorten Time to Value
2. Treat Your Docs Like the Home Page of Your Website
3. Make Abstractions Consistent
4. Future-Proof Your API
## Documentation
Sharing documentation via tools like postman or insomnia is a real game changer IMO
The documentation quality for MSSQL was very good in 2000, and noticeably has deteriorated since then to the point that I (who carefully read the docs) actually released some broken code related to the MSSQL geographical data types (edit: this was in MSSQ 2012). Fortunately cleaning that mess up in the morning while clients were phoning us wasn't too bad, but it could have been.
I also notice that they've made the offline help both hard to get to (you have to install it manually now as a separate process) and inconvenient to use in various small ways. I am certain this is an attempt to push you to use the online help instead. As a professional dev I find this objectionable.
Example: learning C# and their examples didn't ework. Someone else on HN replied and said the same. Turns out they had moved the LINQ functional stuff into a separate module you had to import. Once imported, everything was fine but their examples were broken and there was no way to know what to do - a very simple solution was to get the compiler to recognise that certain stuff was missing when you try to use it and just tell the user. But no, they left you to flounder instead.
Another example: I lost ~1 day trying to start a C# GUI project that just would not show data binding components. Turns out that it had to be a particular project type (not .NET core IIRC) but that was not made clear.
EDIT: oh well too late to do that.