acm-uiuc/groot-api-gateway

API Documentation

narendasan opened this issue · 4 comments

narendasan commented

We need a standard way of documenting the apis we create. There are few tools out there to manage this. RAML and API Blueprint are the best two options for our uses in my opinion. API Blueprint in particular allows both markup and json descriptions of our apis which is nice. RAML is straight json. API Blueprint also has cool plugins to test and display documentation. The ultimate goal is to have a tools that helps use define the API so a script in the gateway can generate the integration (if we create our own gateway).

mathur commented

Is there any guidelines on success/error json right now?

I think a response like:

{
    "code": 404,
    "message": "Not found"
}

(basically generally a code + message field) should suffice? Any more information you want to respond with?

narendasan commented

I think that works, unless there is an error in the middle, the proxy will
forward whatever you send it

On Sun, Nov 15, 2015 at 9:50 PM Rohan Mathur notifications@github.com
wrote:

Is there any guidelines on success/error json right now?

I think a response like:

{
"code": 404,
"message": "Not found"
}

(basically generally a code + message field) should suffice? Any more
information you want to respond with?

—
Reply to this email directly or view it on GitHub
acm-uiuc/groot#24 (comment).

mathur commented

Cool, will do. Thanks!