Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Swagger: A simple, open standard for describing REST APIs with JSON

swagger.wordnik.com

Post reply on HN
Print view View original

11–20 of 26 posts

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#11

Post by ImJasonH »

This is similar in spirit to the Google APIs Discovery Service, an API to describe recent Google APIs. http://code.google.com/apis/discovery/v1/using.html

This is used to power the APIs Explorer, and code/documentation generation for client libraries:

* APIs Explorer: https://code.google.com/apis/explorer

* JavaDoc for the generated Java library for Calendar API: http://javadoc.google-api-java-client.googlecode.com/hg/apis...

* PyDoc for the Python library: http://api-python-client-doc.appspot.com/calendar/v3

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#12

Post by MattJ100 »

Not a new idea, but it seems a pretty implementation. I've played with Spore a little in the past: https://github.com/spore

Client implementations include:

- Perl: https://github.com/franckcuny/net-http-spore

- JS (Node): https://github.com/francois2metz/node-spore

- Lua: https://github.com/fperrad/lua-Spore

- Ruby: https://github.com/sukria/Ruby-Spore

- Clojure: https://github.com/ngrunwald/clj-spore

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#13

Post by coolgeek »

jcromartie wrote: post #7

The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this is exactly the sort of documentation that's helpful for this kind of API.

Just so that I'm clear on this, are you just criticizing that all requests go to /word.json?

IOW, would the following be RESTful?

GET /entries/{word} # Return entries for a word

GET /wordForms/{word} # Rturn other forms for a word

POST /wordForms/{word} # Adds a relationship map for a word

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#14

Post by arethuza »

coolgeek wrote: post #13
jcromartie wrote: post #7

The example demonstrates an RPC-style HTTP API with pretty URLs. There's no hypermedia in sight. Oh well, we'll figure it out one day... That being said, this is exactly the sort of documentation that's helpful for this kind of API.

Just so that I'm clear on this, are you just criticizing that all requests go to /word.json? IOW, would the following be RESTful? GET /entries/{word} # Return entries for a word GET /wordForms/{word} # Rturn other forms for a word POST /wordForms/{word} # Adds a relationship map for a word

I think the point is that if you are documenting the structure of URIs you are focusing on the wrong thing - a RESTful interface documentation should mostly be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in - a particular server should really have the freedom to construct the URIs in any way it wants and still have clients that understand the API work.

See: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#17

Post by earth2marsh »

johnmw wrote: post #16

Does anyone know of a tool that can take a API type schema and can actually generate the API for you? I'm talking about a simple CRUD type APIs for quick development. Ideally it would have user sign up and simple field validation baked in.

Usergrid ( https://apigee.com/usergrid ) addresses at least some of what you're looking for. If you try it, let me know, as I'm part of that team that's working on it.

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#18

Post by smhinsey »

arethuza wrote: post #14
coolgeek wrote: post #13

Earlier quoted context omitted.

Just so that I'm clear on this, are you just criticizing that all requests go to /word.json? IOW, would the following be RESTful? GET /entries/{word} # Return entries for a word GET /wordForms/{word} # Rturn other forms for a word POST /wordForms/{word} # Adds a relationship map for a word

I think the point is that if you are documenting the structure of URIs you are focusing on the wrong thing - a RESTful interface documentation should mostly be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in - a particular server should really have the freedom to construct the URIs in any way it wants and still have clients that understand the API work. See: http://roy.gbiv.com/untangled/2008…

I think when done right (a subjective measurement, to be sure) the only URI you care about for a RESTful API is the root, because the API's resources are defined, along with how they can be manipulated, in the root response or can be transitioned to from there in some way that is defined there.

Re: Swagger: A simple, open standard for describing REST APIs with JSON

#19

Post by jcromartie »

smhinsey wrote: post #18
arethuza wrote: post #14

Earlier quoted context omitted.

I think the point is that if you are documenting the structure of URIs you are focusing on the wrong thing - a RESTful interface documentation should mostly be about the hypermedia (HTML, XML, JSON,...) that the URIs are embedded in - a particular server should really have the freedom to construct the URIs in any way it wants and still have clients that understand the API work. See: http://roy.gbiv.com/untangled/2008…

I think when done right (a subjective measurement, to be sure) the only URI you care about for a RESTful API is the root, because the API's resources are defined, along with how they can be manipulated, in the root response or can be transitioned to from there in some way that is defined there.

Yes, that's the key. If the media types are documented (like how browsers and developers understand HTML forms) then you don't need to document every single corner of the API. You can offer a good definition of the media types, and let the resources and links do the rest.
Post reply on HN