3 ms·

New API Commons Platform Allows Developers to Share APIs

22 points by njyx 13y ago

njyx 13y ago
http://www.apicommons.org http://www.apicommons.org
smizell 13y ago
Hasn't this idea already been explored with registering media types? Isn't this what REST and all of the HTTP specs were meant to address? You use an existing hypermedia type or register a new one, then any client that can read those media types can read your API. I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST. As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward: http://amundsen.com/blog/archives/1147 http://amundsen.com/blog/archives/1147
- njyx 13y ago
  Media types help in one dimension (data model) but they don't give you a complete definition of an API. Also - people aren't actively promoting and re-using them. The main aim here is to try bring the things which are clearly copyright free out into the open so they can be re-used and evolved. This doesn't happen in the REST API space at all right now.
  - smizell 13y ago
    I would say media types don't give you a full definition [1] because they really aren't meant to do so. They are meant to be used to express resources in a certain way that clients and servers can understand them. Additionally, your resources should be described through link relations, which, along with media types, allow your API to be self describing and discoverable. Take, for example, the Business API that is listed on the site [2] and picture Collection+JSON [3] being used to represent the business collection resource and the business item resource. If you used Collection+JSON, what would be left to describe? It would seem like you wouldn't need a Swagger file because your API would be describing itself. Lastly, even though media types may not be actively promoted or used at this time, I think we should push toward promoting really good hypermedia types. Edit: I wanted to also add a couple other interesting media types to check out, HAL [4] and Siren [5]. I'm sure there are other really good ones, too. [1] By definition I'm taking it to mean fully describing an API. [2] https://github.com/ongithub/businesses/blob/gh-pages/businesses https://github.com/ongithub/businesses/blob/gh-pages/busines... [3] http://amundsen.com/media-types/collection/ http://amundsen.com/media-types/collection/ [4] http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html [5] https://github.com/kevinswiber/siren https://github.com/kevinswiber/siren
minor_nitwit 13y ago
In the Future of Programming, Bret Victor talks about how computers should be able to distinguish the API/language of one another using goal directed programming. Is anyone at work on that? It's nice but API documentation isn't usually the problem.
rurounijones 13y ago
Most of those seem hopelessly simple (Just for the image bit, it only has one thumbnailUrl and no thumbnail size information). I understand that this is a basis for further evolution but these APIs are gonna be hitting version 13 before they are usable in the real world and by that point they will probably be skewed towards use cases based on whoever updated them.

22 points by njyx 13y ago

njyx 13y ago

http://www.apicommons.org http://www.apicommons.org

Hasn't this idea already been explored with registering media types? Isn't this what REST and all of the HTTP specs were meant to address? You use an existing hypermedia type or register a new one, then any client that can read those media types can read your API. I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST. As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward: http://amundsen.com/blog/archives/1147 http://amundsen.com/blog/archives/1147

njyx 13y ago
Media types help in one dimension (data model) but they don't give you a complete definition of an API. Also - people aren't actively promoting and re-using them. The main aim here is to try bring the things which are clearly copyright free out into the open so they can be re-used and evolved. This doesn't happen in the REST API space at all right now.
- smizell 13y ago
  I would say media types don't give you a full definition [1] because they really aren't meant to do so. They are meant to be used to express resources in a certain way that clients and servers can understand them. Additionally, your resources should be described through link relations, which, along with media types, allow your API to be self describing and discoverable. Take, for example, the Business API that is listed on the site [2] and picture Collection+JSON [3] being used to represent the business collection resource and the business item resource. If you used Collection+JSON, what would be left to describe? It would seem like you wouldn't need a Swagger file because your API would be describing itself. Lastly, even though media types may not be actively promoted or used at this time, I think we should push toward promoting really good hypermedia types. Edit: I wanted to also add a couple other interesting media types to check out, HAL [4] and Siren [5]. I'm sure there are other really good ones, too. [1] By definition I'm taking it to mean fully describing an API. [2] https://github.com/ongithub/businesses/blob/gh-pages/businesses https://github.com/ongithub/businesses/blob/gh-pages/busines... [3] http://amundsen.com/media-types/collection/ http://amundsen.com/media-types/collection/ [4] http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html [5] https://github.com/kevinswiber/siren https://github.com/kevinswiber/siren

minor_nitwit 13y ago

In the Future of Programming, Bret Victor talks about how computers should be able to distinguish the API/language of one another using goal directed programming. Is anyone at work on that? It's nice but API documentation isn't usually the problem.

rurounijones 13y ago

Most of those seem hopelessly simple (Just for the image bit, it only has one thumbnailUrl and no thumbnail size information). I understand that this is a basis for further evolution but these APIs are gonna be hitting version 13 before they are usable in the real world and by that point they will probably be skewed towards use cases based on whoever updated them.