krsyoung

Very cool. We're facing this common problem where endpoint consumers go query-happy with GraphQL seeing as it is so easy to pull a large amount of data (or trigger a large number of operations).

It is currently very unclear how much load is being caused by the "convenience" of data-based queries. Having the ability to articulate and limit these expensive operations via policy would be incredibly helpful in not only shaping internal behaviour but also in exposing services to broader audiences.

Curious what others in the community have done to hack something similar in place?

All the more motivation for API Providers to publish their specifications so that IDE integrations like this are effective!

I still lean heavily on the framework to help with the API aspects (i.e. Rails, Sinatra, Express, Flask ...). I now consistently (at least in my mind) document the APIs via Open API Specification (swagger) and use that for documentation.

For DB-centric projects I've used things like StrongLoop and DreamFactory which makes turning a DB into a REST API very simply. Key is that the DB is just being turned into REST ... no much logic in the middle.

Foxx looks cool, have not tried it but claims to be similar to Sinatra.

For exposing, it really depends if you are exposing internally or externally. Worth checking out something like Kong to act as your API gateway and leave some of the complexity out of the backend services when / if possible.

Do you think that we need to standardize on extensions? The blog post makes it clear that there is room to add additional information to the OAS document ... the question would be where to draw the line? Maybe there could be "groupings" of vendor extensions that would qualify as some additional class of information?

Vendor extensions are flexible / powerful but how to consolidate such that services consuming API specifications can depend on their existence and understand their semantics?

There are many great options in the list but with the state of industry and the large number of APIs coming out each year Google is still a great place to start!

Curious if folks perform their initial search on any of the sites above or if Google is the one that lands you there?

My take is that Hitch is there to help developers stay informed (via push vs pull) about changes to APIs they are interested in and then to provide a forum to discuss those changes. I think the "marketplace" piece (i.e. Browse APIs) is really just to facilitate the ability to find the API you want to "Follow" for changes.

Hitch looks like a slick iteration on the API Changelog. Any plans to support the ability to search for APIs?

Also curious how Hitch would look if it could more easily detect changes via API providers providing a more formal specification (i.e. versioned Open API Specifications, Blueprint, RAML etc.. that could be diff'd). Guessing it is "challenging" today to either rely on API owners to make updates or to deal with more complicated web scraping.

Good point, think they are broadly used? My experience with the SDK generation has been hit or miss but the intention is good!

I agree with this post. I very rarely consider using a service's API without a client library. Taking the load off authentication and marshaling is incredibly valuable in my development workflow. Granted, sometimes simple REST endpoints are OK if they are public / don't need complicated authentication.

I think the major benefits of client libraries is the ability for a developer to stay within their programming language / business domain and not stray into the fun of HTTP and JSON.

Curious how much burden this makes for providers though and what people have done to streamline the testing of the various client libraries with different versions of the service.

Definitely there are many benefits to having API specifications available (SDK generation, testing, etc.) especially if they can come from the providers as an alternate from human readable documentation. Seems like the challenges presented above are due a 3rd party trying to find / produce swagger where none existed (a truly heroic effort). Goes back to providers publishing some type of API specification just like websites provide sitemap.xml so APIs Guru can move to higher value projects!

You blew my mind a little bit there ... so you're introducing the notion of a super light-weight subscription / payment system to sidecar the API specification itself? This something that would make sense with state-less services vs those requiring some investment by the service provider (i.e. some account with more backend overhead)?

Having the API specification cover more of the business/service aspects is very interesting (could you possibly define cost per call per endpoint or per payload size for instance).

IvanGoncharov, you've done much work in this space in trying to innovate around Web APIs (thanks for that!).

I think realityking nailed it in terms of the API community needing to define compelling use cases. The catch 22 here is that it is hard for people to innovate around API specifications when they are so hard to get! Per the SDKs ... what if there was a NPM.org or rubygems equivalent of high quality SDKs that get automatically generated whenever I push a new API specification? That seems like it could be cool.

And your example of automated composition is fantastic! Curious if you are able to share how much work it is for you to get access to the specifications in order to make this possible? If we invented a common practice to publish something like api.company.com/spec.yaml could you have spent a lot more time on making cool integrations vs mining specs?

First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist).

Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information.

I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!).

The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well.

Interested if others have had luck embedding API specs into code.