5 ms·
Secrets to Great API Design (2019)
- deleted 5y ago[deleted]
- voicedYoda 5y agoThe article brings up interesting points, but reads like I'm blasting through a red bull ad. (Zing Zang Zoom!) API development is super important, and KIS principles should apply, but i felt this post was more marketing and less functional advice.
- nerdyadventurer 5y agoAny good resources on API design?
- eyelidlessness 5y agoSurprisingly enough (to some, including me), Microsoft's REST API design guidelines are both thorough and there's very little I'd object to.
- beebmam 5y agoThere is incredibly good information on Microsoft's site for developers
- BarryMilo 5y agoI'm surprised anyone finds this surprising. Like them or not, Microsoft makes tight documentation for developers.
- eyelidlessness 5y agoI found it surprising because I interacted with their REST APIs first. They are very good about docs. The ones I use most frequently (TS) are no exception, though they have some gaps. But the actual REST APIs I integrated very clearly predate a lot of their guidelines or struggle to follow them.
- blowski 5y agoThat's true of everything I've worked on. Little details keep sullying my perfect design for reasons end users aren't aware of.
- Xelbair 5y agomaybe they are able to create good docs, and good guidelines, because they burned themselves in the past creating godawful ones?
- nl 5y agoI don't remember any bad MS docs and I've been using them on and off since the 1990.
- zasdffaa 5y agoA Microsoft are very good at telling you (usually) what's there but they don't like telling you what's missing or what's inconvenient to use. Or indeed, what they have downright deliberately broken. 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.
- metachris 5y agohttps://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design https://docs.microsoft.com/en-us/azure/architecture/best-pra...
- systemvoltage 5y agoThere was just an article on HN a couple of days ago: https://news.ycombinator.com/item?id=30647784 https://news.ycombinator.com/item?id=30647784 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.
- Mandatum 5y agoLiterally all API design articles are marketing. There’s almost zero, aside from foundations that came from academia, early industrial or military specs, or very shallow blog posts that are almost useless when you actually build something beyond a prototype.
- rco8786 5y agoThis post is literal content marketing. Not in a bad way, but that's what it is.
- dbsmith83 5y ago> Learn how to make your API stand out from the rest ... I see what did there
- politelemon 5y ago> It may be better to add GraphQL APIs. 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.
- addet0x 5y agoYou should never add something coming from Facebook without quite some hesitation. Their mantra "move fast and break things" broke more things than they could have imagined. GraphQL isn't great, it isn't even average. It's actually pretty terrible. It's just another query language and actually you don't need it. Steer clear from it.
- jack335 5y agogreat article! 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
- mkoubaa 5y agoI'm not sure how I feel about the term API being used unqualified to refer exclusively to SaaS remote APIs. API design is really important for any kind of library or module.
- tabtab 5y agoThe best API's fit how users actually use them. I'm not sure there is a one-design-fits-all. One has to study to see what's done the most often and optimize around those, yet still allow flexibility for the times that deviate from common usage patterns. Make the common stuff short and easy, but the uncommon stuff possible and clear-cut. It may take a couple of iterations in actual use to tune it. 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.
- password4321 5y ago2 days earlier, 200 more comments: How to Design Better APIs | https://news.ycombinator.com/item?id=30647784 https://news.ycombinator.com/item?id=30647784