API Documentation

The Microbrewit API is a RESTful API that consist of a series of resources (users, recipees, breweries, etc) each with it's own route (api.microbrew.it/user/...). The API is developed according to format rules provided in the JSON API draft.

Requests

The API use various forms of requests depending on the action being done for a resource. Each request will return a standard json response. If you want to use the API from within a browser you need to include a named parameter callback in the request, with a function name as value. This name will be used to wrap the JSON response. See JSONP on Wikipedia for more information.

Responses

The API returns JSON responses in two general forms:

Message responses

{'message': 'Info about response',
'something', 'somevalue'}

All message responses includes a message key with a corresponding string value. This is used to provide information about the response. The response object can also include other data depending on which URL is requested.

Example:http://api.microbrew.it/user/login/bob?password=pass&callback=userlogin

Yields:userlogin({})

Error responses:

{'error': 'Info about error',
'errorcode', 'somecode'}

Error response objects will always include an error key which can be used to identify when errors occur. They will also include an error code which can be used to identify the nature and origin of the errors. The error object may include other information as well.

API URLs

Users

Add or update user

POST - api.microbrew.it/user/add Use this endpoint to add or edit users. The API will automatically determine if a user exists or not, and add or update the user correspondingly.

Example usage:

#####Add Request: Send a POST request with the following parameter value pairs...

id => thisismyusername
email => some@email.com
breweryName => My Awesome Brewery
settings: => {}

Response:

{
meta: {
  total: 1236,
  returned: 1,
  skip: 0,
  size: 20
},
users: [{
  id: 'thisismyusername',
  href: 'http://api.microbrew.it/user/thisismyusername',
  username: 'thisismyusername',
  email: 'some@email.com',
  breweryName: 'My Awesome Brewery',
  settings: {}
  }]
}

#####Update: Send a POST request with the following parameter value pairs...

id => thisismyusername
email => new@email.com
breweryName => My Not So Awesome Brewery
settings: => {}

Response:

{
meta: {
  total: 1236,
  returned: 1,
  skip: 0,
  size: 20
},
users: [{
  id: 'thisismyusername',
  href: 'http://api.microbrew.it/user/thisismyusername',
  username: 'thisismyusername',
  email: 'new@email.com',
  breweryName: 'My Not So Awesome Brewery',
  settings: {}
  }]
}

User login

POST - api.microbrew.it/user/login/:username

User logout

GET - api. microbrew.it/user/logout/:username

User update

POST - api.microbrew.it/user/update/:username (username needs to be implemented in node api) Request params: “email”, “password” and “settings”.

User(s) details

GET - api.microbrew.it/user/:userids

Example usage:

Single user: http://api.microbrew.it/user/thisismyusername

{
meta: {
  total: 1236,
  returned: 1,
  skip: 0,
  size: 20
},
users: [{
  id: 'thisismyusername',
  href: 'http://api.microbrew.it/user/thisismyusername',
  username: 'thisismyusername',
  email: 'some@email.com',
  breweryName: 'My Awesome Brewery',
  settings: {}
  }]
}

Beer

Beers are resources that contain details (e.g description, brewery, ABV), (optionally) a recipe and (optionally) information about what beer it is a fork or clone of.

Add/update beer

POST - api.microbrew.it/beer

Example usage

New beer

name => "name of beer",

Fork

fork => api.microbrew.it/beer/somebrewery/sdfkjsfdjkls/mybeer

Clone

clone => api.microbrew.it/beer/somebrewery/sdfkjsfdjkls/mybeer

List Beers

GET - api.microbrew.it/beer

Single Beer object (everything)

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer

Details (meta info)

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/details

Recipe

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/recipe

Forks

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/forks

Clones

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/clones

Parent

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/parent

Children

GET - api.microbrew.it/beer/:breweryname/:breweryid/:beer/children

Breweries

Breweries are resources that beers are connected to. A brewery can be either commercial (e.g macro brewery, micro brewery or nano brewery) or non-commercial (home brewery).

Add/Update Brewery

POST - api.microbrew.it/brewery

List Breweries

GET - api.microbrew.it/brewery

Brewery

GET - api.microbrew.it/brewery/:breweryid

Details

GET - api.microbrew.it/brewery/:breweryid/details

Beers

GET - api.microbrew.it/brewery/:breweryid/beer

Brewers

GET - api.microbrew.it/brewery/:breweryid/brewers

Ingredients

Fermentables

Add/update fermentable

POST - api.microbrewit/fermentable

List fermentables

GET - api.microbrewit/fermentable

Get fermentable

GET - api.microbrewit/fermentable/:fermentable

Request params: ….

Hops

Add/update hops

POST - api.microbrewit/hops

List hops

GET - api.microbrewit/hops

Get single hop

GET - api.microbrewit/hops/:hops

Other

Other ingredients include fruits, infermentable sugars and other things.