ttezel / unio Goto Github PK

I'm seeing gzipped output from the stackexchange api. How do I handle this with unio?

https://api.stackexchange.com/docs/compression

I like the idea to write specs in JSON 👍

Moreover, this can be used in a HTML web page as a documentation, just by parsing the JSON document in javascript and creating a complete and clean documentation.

But for that, I feel like the actual spec is missing some important key points, like the description of each resources and params.

Here an example of an opinion I have for adding description and then improving JSON description of REST API services :

{
    "name": "twitter",
    "api_root": "https://api.twitter.com/1.1",
    "resources": {
        "account/settings":{
            "path": "account/settings.json",
            "methods": [ "get" ],
            "description": "Returns settings (including current trend, geo and sleep time information) for the authenticating user.",
            "params": [
                {
                    "name": "oauth",
                    "state": "required",
                    "description": "OAuth token required to execute this request.",
                },
                {
                    "name": "count",
                    "state": "optional",
                    "description": "Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.",
                }
            ]
        },
    // ...
}

Doing this, even the author of this documentation can build a documentation in just a single html page that updates itself automatically when the documentation is updated! :)

I was looking at how APIhub stores the JSON description of an API, and I was wondering if it would be worth it to use specs in that style? APIhub seems to have a decent many of them already mapped out. (Note: View it more easily here) At the very least, more specs could be crawled from that data. (If that's legal and morally okay).

Hi,

I'm doing kind of the same thing but we're trying to use an unified format, namely SPORE, available here: https://github.com/SPORE/specifications

And a python client over there: https://github.com/spiral-project/respire

Maybe we should collaborate on this?

For example consider the facebook api errors here.

We can easily map non-200 responses to create errors from the response body.

@ttezel should the callbacks be invoked with (err, res, body) where err would be an error with error message and body is the parsed response body, or attach the response body on the err object (err.body) and callback with (err, res)?

eg. the github spec

{
    "name": "github",
    "api_root": "https://api.github.com",
    "resources": {
        "authorizations": {
            "path": "authorizations",
            "methods": [ "post", "get" ],
            "params": [
                {
                ....
}

has the resource name as 'key' to the resource 'object'.

however the twitter spec defines the resource name as part of the object.
Maybe it is nice to choose one format as reference for implementations of Unio in other languages? Maybe it might also be nice to have the specs complete for those included in Unio?

Why create a new description language for RESTful services? Why not use WADL: http://en.m.wikipedia.org/wiki/Web_Application_Description_Language

eg. we can have GET /user accept different params than POST /user, by allowing multiple resource definitions with the same url path.

The PATCH method is used by Backbone.js apps to perform partial updates (where a PUT must describe the entire resource). It would be useful/easy to add this in.

Having a little trouble using :params in a quickie instagram spec.

I have the following in the spec:

    {
      "name": "tags/:id",
      "path": "tags/:id",
      "methods": [
        "get"
      ],
      "params": {
        "access_token": "required"
      }
    },
    {
      "name": "tags/:id/media/recent",
      "path": "tags/:id/media/recent",
      "methods": [
        "get"
      ],
      "params": {
        "min_id": "optional",
        "max_id": "optional",
        "access_token": "required"
      }
    },

But when I make the following request:

.get('tags/'+tag+'/media/recent', {'access_token':at}, function (err,resp,body) {

Unio seems to hit on "tags/:id" and not "tags/:id/media/recent".

Suggestions?

Hi ttezel, when I try to use twitter from unio i get

[ { message: 'The Twitter REST API v1 is no longer active. Please migrate to API v1.1. https://dev.twitter.com/docs/api/1.1/overview.',
code: 68 } ] }

Is it in pipeline twitter API update ?

Thanks!

Might it be benificial to include a json description of the expected data in the response?
This could make it possible to have a client user to supply callbacks to instantiate objects or parse response data.

The PATCH method is used by Backbone.js apps to perform partial updates (where a PUT must describe the entire resource). It would be useful/easy to add this in.

I think this is a great idea! There is currently a JSON schema draft that various validators and tools follow. If implemented this would help a lot of unknown providers quickly comply.

Resources:
http://tools.ietf.org/html/draft-zyp-json-schema-03
http://json-schema.org/implementations.html
http://www.jsonschema.net/faq.html

Please add the ability to define custom request headers. This should support statically defined headers that are the same for every request, as well as headers that are required with dynamic values for each request (e.g. a custom header specifying a session ID), and headers that are defined to be present only for specific requests.