21–30 of 47 posts
Because--oh I don't know--APIs aren't restaurants?
Is this really a problem, or is this a tool to help lazy blub developers be even lazier and blubbier?
If you care enough about an API to worry about what things it does via the docs--and why aren't you using a client lib anyways?--then you care too much to be satisfied with a simple sketch of the API via Google search results.
JSON-LD provides a vocabulary (schema) for linking various documents together, so you can for example link a blog post document directly to its author. Hydra then provides a vocabulary that lets you describe how to fetch that author document, what fields are required to create a new author object, and how to update the blog post to instead link to that new author. In this case, both "author" and "blog post" can be their respective schema.org documents.
[1]: http://www.hydra-cg.com/ [2]: http://json-ld.org/
Semi-related question: is there a list of things that actually use Schema.org, outside of Google Search for some things?
I put together a side project some time ago that allows you to retrieve and display arbitrary API endpoints, to create a dashboard of realtime data. One of the bigger challenges was finding appropriate APIs to use. The idea being that it had to make sense as a realtime datapoint. Current temperature in California is one example. Part of the solution I tried for the end user was to add a searchable database of APIs, b…
This is stupid. The solution is the semantic web.
> Then you automatically assume it’s a REST API using JSON payloads. Who’s doing anything else nowadays? I'm seeing people using GraphQL[1] more these days, which also solves the problem of API schema discovery because it's one endpoint with built-in introspection[2]. [1] https://graph.cool/ [2] http://graphql.org/learn/introspection/
> people using GraphQL[1] more these days
I fully agree. That's why we also maintain a list of GraphQL APIs: https://github.com/APIs-guru/graphql-apis
> solves the problem of API schema discovery because it's one endpoint with built-in introspection
You're absolutely right. We plan to do a few interesting projects around GraphQL. Subscribe to our blog to not miss announcements :)
This is stupid. The solution is the semantic web.
I wonder if the author knows about Swagger specs; They also started the OpenAPI initiative[0]. I now have wrapped a couple of API's in swagger and using swagger-ui to create beautiful interactive api docs for users. Moving forward I'm going to wrap most of our legacy systems around a swagger spec'ed API and discontinue any alternative access to these systems as time goes by. [0]: http://swagger.io/introducing-the-ope…
Hi, I'm the author, and I definitely know about Swagger/OpenAPI. By coincidence, I'm maintainer of the collection of 250+ Swagger specs for public APIs: https://github.com/APIs-guru/openapi-directory But I have learned the hard truth over last two years: API catalogs aren't scalable solutions for API discovery. That's why I'm pushing this. P.S. it is pretty easy to generate Schema.org type based on Swagger/OpenAPI sp…
Minor critique but the word "discovery" particularly in terms of service oriented is heavily overloaded. It took me a little while to understand what the article meant by discovery and I'm still not entirely sure I do.
Do you mean this discovery: https://en.wikipedia.org/wiki/Service_discovery or do you mean a discovery more in the human sense (ie a consumer search directory listing API services)?
It sounds like what you're describing is very similar to Hydra[1], which builds upon JSON-LD[2], which builds upon schema.org. JSON-LD provides a vocabulary (schema) for linking various documents together, so you can for example link a blog post document directly to its author. Hydra then provides a vocabulary that lets you describe how to fetch that author document, what fields are required to create a new author ob…