Wednesday, October 01, 2014

Working With Apiary.io - Create RESTful WebService Documentation Much Easier

Creating RESTful WebService Doesn't matters here.It matters about how you Provide Documentation for your Users/Developers to consume your web service in Rightful manner.You Need to Create Your Best out of for Documentation and clearly explain with some kind of Demo or Else Developers may seek through Stackoverflow and other forums to resolve their Problem and May hinder development of Apps.apiary.io provides default doc for every API project you create.

Learn Here to create RESTful Webservice using Node.js/Mongoose dB

Working With Apiary.io - Create RESTful WebService Documentation Much Easier


Getting Started :  Visit Demo

Create an Account at apiary.io website and create a Domain in your favour and you can find sample coding for notes API.
Either you can simply Edit that API content and implement yours or else just follow below ideas/procedures to build a Successful API Documentation.

Host and Version For API :


 FORMAT: 1A

 HOST: http://api.example.com/



Name your API with Short Description:




 # Film API
 Film API Web Service Done with Help of Node.js as Backend.


Create a group :


 # Group film
 This Route film can get recent films and post new films


Categorize Your API Routes :


 ## film Routes [/films]


This will automatically create as /film below for each route you define.

Define Each of Your Route :

Here indentation is more important to overcome Symantic Errors.Either 8 Space bar or two Tab key press.



 ### List popular film [GET]
 + Response 200 (application/json)

        [{
          "id": 1, "title": "Neethane En Ponvasantham","genre":"love"
        }, {
          "id": 2, "title": "Moonu - 3 Film","genre":love"

        }]


Actually above Hash(#) must be thrice for defining completely your route with a Name of the route with REQUEST TYPE in SQUARE BRACKET.

Next Step define your Response with HTTP Status code and with return type of Response.
and With Enter key followed with Two tab spaces start typing example results from server

POST request : 


 ### Create a film [POST]
 + Request (application/json)

        { "title": "Yaan","genre":"action" }

 + Response 201 (application/json)


        { "id": 3, "title": "Yaan","genre":"action" }


Routes With Parameters :

Generally Parameters are passed via URL(Actually here URI) to make a GET/DELETE/PUT request.you must clearly specify the Data type and purpose of Parameters to be passed and gain expected data.

Define A specific Routes to categorize since the same uri can be used for GET , POST , PUT.


 ## Film By ID [/film/{id}]
 A single Film Details is performed here

 + Parameters
     + id (required, number, `1`) ... Numeric `id` is unique value given to the Each Film.


As like before follow the indentation here too.Either 8 spaces/two tabs.

Define Each Route Below.


### Retrieve a film  [GET]
+ Response 200 (application/json)

    + Header

            X-My-Header: The Value

    + Body

            { "id": 2, "title": "Neethane En Ponvasantham","genre":"love" }

### Remove a film [DELETE]
+ Response 204




Thus We have Define a Successful doc for our Successful API with Apiary.io,Just preview with Apiary and make changes.

Have a look at my Simple Film API snapshot : visit for full Demo here

Working With Apiary.io - Create RESTful WebService Documentation Much Easier


The Above Screenshot of My API service for film API.

Caution : 
Don't Follow above Example codes,those are not formatted with tabs/Spaces
The Sample will be working only if you add correct host,and make sure of CORS policy of Ajax to run sample properly.Indentation for Response,Request is more important.Either(8 spaces/2 Tabs).

For bugs/comments/suggestions/errors comment below or mail me [email protected] or connect with me in Facebook/Twitter.Feel free to comment below.Share is care.

0 comments:

Post a Comment

feel free to post your comments! Don't Spam here!