6 ms·

API Improvement Proposals

85 points by bshanks 5y ago

gravypod 5y ago
AIP is a great start but I hope people extend the ideas here a little more. A lot of this is centered around conventions that make sense to humans and to automated API generators (see Long Running Operations for an example of this). I hope at some point someone builds more gRPC-specific API recommendations that includes streaming and ways to do a better bulk data transfers. (ex: stream-with-filters) However, applying most of these proposals has improved APIs I've worked with and written.
- teknopaul 5y ago
  defo feel like more work is needed, perhaps some new ideas. async apis are needed too IMHO, some framework that permits consistent apis that can be http or stomp or websockets if those protocols are a better fit.
  - teknopaul 5y ago
    I would appreciate an api framework that can handle email as a transport.
- axegon_ 5y ago
  > I hope at some point someone builds more gRPC-specific API recommendations that includes streaming and ways to do a better bulk data transfers. (ex: stream-with-filters) I'm currently working on migrating a system from the Google Adwords API(being depricated in some months) and porting everything to their new Google ads API(a massive step up) and to be honest everything described here is incredibly familiar. Overall that's exactly how it works.
teknopaul 5y ago
Rest is great, but. We have something similar where I work and it has done great things for API consistency. But the efficiency of resulting implementations is not good. We have no solution for simple task oriented apis like change-password. In these cases rest is fugly. I'm still looking for some good API guidelines for rpc that are not resource oriented and don't accidentally result in hundreds of new methods.
- dopaminefasting 5y ago
  When you say you have no solutions for change-pass, what exactly is the stumbling block here. As for RPC guidelines, they match the same guidelines you'd have writing a native API as a set of interfaces. You already know how that works. Just apply it. If I'm wrong, let me know what's the issue.
the_arun 5y ago
We need similar guidelines for distributed Application Development (in the lines of OAM - https://oam.dev/ https://oam.dev/ or https://dapr.io https://dapr.io)
barnabask 5y ago
Really looking forward to our AIP Project Implementation, or API.
seph-reed 5y ago
I'm a crazy person who doesn't really use the "standard" functions for my APIs. Instead I revolve around getIdAndFreshnessList(filter) and getItems(ids). I've built tools to store items locally, and check if the id is cached and the date is fresh, and only request things that need updating. I'm digging myself into a hole of being "too different" again. This is just another convention I'll be judged negatively against.
- sillysaurusx 5y ago
  Nothing wrong with that. That's how I've built scraper systems in the past. It's nice for getting historical snapshots of live data. The trouble comes in when you want to do something that you know will modify the result. (The "request things that need updating" part was surprisingly hard for me; if an item is modified but the old cached copy is still being served, it became problematic for me to rely on it.)
sillysaurusx 5y ago
Is it a mistake that their website <title> is "AIP Improvement Proposals"?
- spondyl 5y ago
  Hmm, yes I suppose that would make it "API Improvement Proposals Improvement Proposals"
- boulos 5y ago
  Huh, I was going to send Luke a pull request, but he actually fixed this in late May [1]. Maybe he needs to re-generate the site? [1] https://github.com/aip-dev/site-generator/commit/9fe7bdcf83cfdcea1c4d30cef6dacd988f77e2e0 https://github.com/aip-dev/site-generator/commit/9fe7bdcf83c...
deleted 5y ago
[deleted]

85 points by bshanks 5y ago

AIP is a great start but I hope people extend the ideas here a little more. A lot of this is centered around conventions that make sense to humans and to automated API generators (see Long Running Operations for an example of this). I hope at some point someone builds more gRPC-specific API recommendations that includes streaming and ways to do a better bulk data transfers. (ex: stream-with-filters) However, applying most of these proposals has improved APIs I've worked with and written.

teknopaul 5y ago
defo feel like more work is needed, perhaps some new ideas. async apis are needed too IMHO, some framework that permits consistent apis that can be http or stomp or websockets if those protocols are a better fit.
- teknopaul 5y ago
  I would appreciate an api framework that can handle email as a transport.
axegon_ 5y ago
> I hope at some point someone builds more gRPC-specific API recommendations that includes streaming and ways to do a better bulk data transfers. (ex: stream-with-filters) I'm currently working on migrating a system from the Google Adwords API(being depricated in some months) and porting everything to their new Google ads API(a massive step up) and to be honest everything described here is incredibly familiar. Overall that's exactly how it works.

teknopaul 5y ago

Rest is great, but. We have something similar where I work and it has done great things for API consistency. But the efficiency of resulting implementations is not good. We have no solution for simple task oriented apis like change-password. In these cases rest is fugly. I'm still looking for some good API guidelines for rpc that are not resource oriented and don't accidentally result in hundreds of new methods.

dopaminefasting 5y ago
When you say you have no solutions for change-pass, what exactly is the stumbling block here. As for RPC guidelines, they match the same guidelines you'd have writing a native API as a set of interfaces. You already know how that works. Just apply it. If I'm wrong, let me know what's the issue.

the_arun 5y ago

We need similar guidelines for distributed Application Development (in the lines of OAM - https://oam.dev/ https://oam.dev/ or https://dapr.io https://dapr.io)

barnabask 5y ago

Really looking forward to our AIP Project Implementation, or API.

seph-reed 5y ago

I'm a crazy person who doesn't really use the "standard" functions for my APIs. Instead I revolve around getIdAndFreshnessList(filter) and getItems(ids). I've built tools to store items locally, and check if the id is cached and the date is fresh, and only request things that need updating. I'm digging myself into a hole of being "too different" again. This is just another convention I'll be judged negatively against.

sillysaurusx 5y ago
Nothing wrong with that. That's how I've built scraper systems in the past. It's nice for getting historical snapshots of live data. The trouble comes in when you want to do something that you know will modify the result. (The "request things that need updating" part was surprisingly hard for me; if an item is modified but the old cached copy is still being served, it became problematic for me to rely on it.)

sillysaurusx 5y ago

Is it a mistake that their website <title> is "AIP Improvement Proposals"?

spondyl 5y ago
Hmm, yes I suppose that would make it "API Improvement Proposals Improvement Proposals"
boulos 5y ago
Huh, I was going to send Luke a pull request, but he actually fixed this in late May [1]. Maybe he needs to re-generate the site? [1] https://github.com/aip-dev/site-generator/commit/9fe7bdcf83cfdcea1c4d30cef6dacd988f77e2e0 https://github.com/aip-dev/site-generator/commit/9fe7bdcf83c...

deleted 5y ago

[deleted]