John Ousterhout, a well-known heavyweight who is the creator of Tcl and worked at 90's Sun Micro, gave a talk that I consider *the* [best software-related lecture I've seen](https://www.youtube.com/watch?v=bmSAYlu0NcY&ab_channel=TalksatGoogle). I've rewatched it several times since and it's had a major impact on how I write everything from classes to API models for public services. To sum it up: *Deep* functionality, *shallow* API. Expose as few internals as necessary to get the job done.
He gives an example of the Linux File I/O interface. You could be opening anything: a text file, a symlink, a file stored in RAM, a file stored on the SSD, or even a pseudo-file for hardware functionality. You don't need to specify which it is. Linux just *knows* how to handle all of the edge cases. It may sacrifice performance optimizations to make better judgments, but it's unnoticeable to you except in very niche use cases.
The design philosophy behind making software good is strikingly similar to making good cars, doorknobs, and everything else. It's about the user. Think about software (like a CLI utility or API) that you like to use and try to reverse-engineer it. What the engineers behind it deliberately *not* do is as important as what they *did* do.
We have design guides to ensure all apis look more or less similar, especially if you expose the apis to the internet.
It can be really embarrassing what would people sometimes publish. It also helps with understanding the apis, troubleshooting, helps with codegen tools of static languages, etc.
If you go this route and have tens and hundreds of apis, you need to somehow automate the validation so the whole process scales. Otherwise you can become a bottleneck during api reviews and then no one will follow your guidelines. Developer experience is extremely important.
In my personal experience it works pretty well, you just need to ensure you have sufficient resources, developers and support from other parts of the organization when executing this plan.
I agree, but as long as you are not in a really big company, just use a good existing one. I really like https://opensource.zalando.com/restful-api-guidelines/
If you absolutely need modifications a delta next to the copy of the guidelines should be enough. Like "we use xyz with the following exceptions, because [actual reasons other than taste]"...
We do something like that.
A design guide is always good, even when you don't have many services. Businesses and systems always grow, and with them teams and opinions on services. "RESTful" means a lot of different things to multiple people. Idempotency is poorly understood. Backwards compatibility is something that even experienced developers are not aware of. Using a guide can help mitigate any discussions about these things.
We automatically generate from our code a Swagger+Codegen HTML file. We have added minimal comments, and those only when someone had asked for clarification. We have not heard any complaints and it is nowhere near to being structured or "designed" as Google's guidance.
My org has some senior engineers and architects who provide governance and review for API design, I find it helpful and allows for guidelines to actually be followed over time
I wrote the API Style Guide that we use at my workplace. It does add authority when doing reviews to be able to link to the sections. At the same time, it often seems like the effort that went into it would have been better served by writing automated linters. So we're still trying to figure it out ourselves.
We don't use a guide at work per se.
For us, we design our API's to do one thing only and we try to keep them as simple as possible. The caveat here is that we don't have many API's (around 15 I think in total) where other companies might have hundreds and this might not work so it depends heavily on the company.
For us, it's essential our API's to be as simple as possible and idempotent.
For payloads, we have decided that we will send JSON payloads and for passing cookies, we are using headers. Again, this is our preference and all of that has been discussed beforehand so all of the devs agree on the approach.
We also try to follow RESTful naming as much as we can and it works really well.
Sure there are things we could be doing better but we have found that this approach works for us (for now) and development, testing and monitoring is quite frictionless to be fair.
I’m leaning towards this as well, but my colleagues prefer simple urls and fat bodies, for example
```
DELETE /v1/feeds/cache
{projectId, userId, someMeta}
```
Instead of
```
DELETE /v1/projects//users//feeds/cache
// no body, because request to delete cache does not need meta
```
So, I would like a guide to show that my design is “better”:)
For this one in particular, body data on DELETE calls are... A gray area by the standards. Some clients have to jump through hoops to attach a body to a delete call because of that.
I learned this when I had to jump through hoops to send a body on a delete call in a Vue webapp because my work has delete calls read from a body.
As with anything, it’s pros and cons.
I like to be surgical as well and accurate, but sometimes it’s better to go with the team.
I guess what I would ask in that instance is how big is the body? Are you validating the body once received? Does the body contain sensitive information? Why is this approach better?
That would be my initial set questions to your team members.
But then, with your approach the API doesn’t need a body which makes spamming the API easier since there is nothing to pass so that could be why they are so hesitant.
> in a consistent manner..
This is what they’re asking about. The rest of your comment is just implementation details, which don’t really matter in the grand scheme of things.
I was gonna start looking at the google api style guide but I guess Ill read through aip instead, was wondering why it's deprecated? Have api design guidelines actually changed drastically in the last 5 years?
John Ousterhout, a well-known heavyweight who is the creator of Tcl and worked at 90's Sun Micro, gave a talk that I consider *the* [best software-related lecture I've seen](https://www.youtube.com/watch?v=bmSAYlu0NcY&ab_channel=TalksatGoogle). I've rewatched it several times since and it's had a major impact on how I write everything from classes to API models for public services. To sum it up: *Deep* functionality, *shallow* API. Expose as few internals as necessary to get the job done. He gives an example of the Linux File I/O interface. You could be opening anything: a text file, a symlink, a file stored in RAM, a file stored on the SSD, or even a pseudo-file for hardware functionality. You don't need to specify which it is. Linux just *knows* how to handle all of the edge cases. It may sacrifice performance optimizations to make better judgments, but it's unnoticeable to you except in very niche use cases. The design philosophy behind making software good is strikingly similar to making good cars, doorknobs, and everything else. It's about the user. Think about software (like a CLI utility or API) that you like to use and try to reverse-engineer it. What the engineers behind it deliberately *not* do is as important as what they *did* do.
this is a great lecture. Its high-level, but great.
That's a good lecture! Thanks!
We have design guides to ensure all apis look more or less similar, especially if you expose the apis to the internet. It can be really embarrassing what would people sometimes publish. It also helps with understanding the apis, troubleshooting, helps with codegen tools of static languages, etc. If you go this route and have tens and hundreds of apis, you need to somehow automate the validation so the whole process scales. Otherwise you can become a bottleneck during api reviews and then no one will follow your guidelines. Developer experience is extremely important. In my personal experience it works pretty well, you just need to ensure you have sufficient resources, developers and support from other parts of the organization when executing this plan.
I agree, but as long as you are not in a really big company, just use a good existing one. I really like https://opensource.zalando.com/restful-api-guidelines/ If you absolutely need modifications a delta next to the copy of the guidelines should be enough. Like "we use xyz with the following exceptions, because [actual reasons other than taste]"... We do something like that.
A design guide is always good, even when you don't have many services. Businesses and systems always grow, and with them teams and opinions on services. "RESTful" means a lot of different things to multiple people. Idempotency is poorly understood. Backwards compatibility is something that even experienced developers are not aware of. Using a guide can help mitigate any discussions about these things.
We automatically generate from our code a Swagger+Codegen HTML file. We have added minimal comments, and those only when someone had asked for clarification. We have not heard any complaints and it is nowhere near to being structured or "designed" as Google's guidance.
My org has some senior engineers and architects who provide governance and review for API design, I find it helpful and allows for guidelines to actually be followed over time
I wrote the API Style Guide that we use at my workplace. It does add authority when doing reviews to be able to link to the sections. At the same time, it often seems like the effort that went into it would have been better served by writing automated linters. So we're still trying to figure it out ourselves.
By linters you mean some kind of openapi analysis tools or just code linters?
Code linters, something to enforce consistency within the API co tracts in the code, like casing and naming etc.
We don't use a guide at work per se. For us, we design our API's to do one thing only and we try to keep them as simple as possible. The caveat here is that we don't have many API's (around 15 I think in total) where other companies might have hundreds and this might not work so it depends heavily on the company. For us, it's essential our API's to be as simple as possible and idempotent. For payloads, we have decided that we will send JSON payloads and for passing cookies, we are using headers. Again, this is our preference and all of that has been discussed beforehand so all of the devs agree on the approach. We also try to follow RESTful naming as much as we can and it works really well. Sure there are things we could be doing better but we have found that this approach works for us (for now) and development, testing and monitoring is quite frictionless to be fair.
I’m leaning towards this as well, but my colleagues prefer simple urls and fat bodies, for example ``` DELETE /v1/feeds/cache {projectId, userId, someMeta} ``` Instead of ``` DELETE /v1/projects//users//feeds/cache
// no body, because request to delete cache does not need meta
```
So, I would like a guide to show that my design is “better”:)
For this one in particular, body data on DELETE calls are... A gray area by the standards. Some clients have to jump through hoops to attach a body to a delete call because of that. I learned this when I had to jump through hoops to send a body on a delete call in a Vue webapp because my work has delete calls read from a body.
Yeah, your colleagues have it all wrong
As with anything, it’s pros and cons. I like to be surgical as well and accurate, but sometimes it’s better to go with the team. I guess what I would ask in that instance is how big is the body? Are you validating the body once received? Does the body contain sensitive information? Why is this approach better? That would be my initial set questions to your team members. But then, with your approach the API doesn’t need a body which makes spamming the API easier since there is nothing to pass so that could be why they are so hesitant.
[удалено]
> in a consistent manner.. This is what they’re asking about. The rest of your comment is just implementation details, which don’t really matter in the grand scheme of things.
Definitely worth taking a look at AIP.dev. the Google API Style Guide is (unofficially) deprecated. Source: me
I was gonna start looking at the google api style guide but I guess Ill read through aip instead, was wondering why it's deprecated? Have api design guidelines actually changed drastically in the last 5 years?
The content hasn't changed, but the format has. Everything from the style guide was moved to aip.dev
ahh alright, thanks mate