Skip to content

API Documentation

Jump to bottom Edit New page
John Fredrik Asphaug edited this page Aug 7, 2013 · 32 revisions

NOTE: The Microbrewit API backend is under active development and pre-alpha build. The API will continue to evolve as changes and decisions are made. The API specification will be locked down as the beta draws closer.

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.

Params

  • id (String) Required
  • email (String) Required
  • breweryName (String) Required
  • settings (JSON object as String) Required

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 Retrieves a filtered list of beers given a set of parameters. The request

Parameters

  • size (number between 0 and 100) Required
  • skip (number between 0 and returned) Required
  • username (String) Optional
  • beername (String) Optional
  • brewery_name (String) Optional
  • type (String) Optional
  • abv_min (number between 0.0 and 100.0) Optional
  • abv_max (number between 0.0 and 100.0) Optional
  • ibu_min (number between 0 and 100) Optional
  • ibu_max (number between 0 and 100) Optional
  • srm_min (number between 0 and 100) Optional
  • srm_max (number between 0 and 100) Optional

Example usage

Find all beers with name containing Awesomebeer

Parameters:

size: 20,
skip: 0,
beername: Awsomebeer

Returns:

{
meta: {
  total: 123608,
  returned: 2,
  skip: 0,
  size: 2
},
links: {
  beer.brewery: {
    href: 'http://api.microbrew.it/brewery/:breweryid/',
    type: 'brewery'
  }
},
beers: [{
  id: 'http://microbrew.it/ontology/Beer/:breweryname/:breweryid/Awesomebeer',
  href: 'http://api.microbrew.it/beer/:breweryname/:breweryid/Awesomebeer',
  brewery: 'My Brewery',
  beername: 'Awesomebeer',
  type: 'Wit',
  abv: 4.56,
  ibu: 20,
  srm: 20,
  links: {
    breweryId: '123612467659876'
  },
{
  id: 'http://microbrew.it/ontology/Beer/:breweryname/:breweryid/Awesomebeer2',
  href: 'http://api.microbrew.it/beer/:breweryname/:breweryid/Awesomebeer2',
  brewery: 'My Brewery',
  beername: 'Awesomebeer2',
  type: 'Triple',
  abv: 9.56,
  ibu: 30,
  srm: 40,
  links: {
    breweryId: '123612467659876'
  }
}]
}

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.microbrew.it/fermentables

List fermentables

GET - api.microbrew.it/fermentables

Get fermentable

GET - api.microbrew.it/fermentables/:fermentable Returns

{
meta: {
  total: 123608,
  returned: 1,
  skip: 0,
  size: 1
},
links: {
  fermentables.maltster: {
    href: 'http://api.microbrew.it/maltsters/:maltsterid/',
    type: 'maltster'
  
},
  fermentables.type: {
    href: 'http://api.microbrew.it/fermentebles/types/:typeid/',
    type: 'type'
},
fermentables: [{
  id: 'http://microbrew.it/ontology/fermentables/:fermentable',
  href: 'http://api.microbrew.it/fermentables/:fermentable',
  maltster: 'My supplier',
  name: 'Awesomemalt',
  colour: '100',
  ppg: '20',
  type: 'grain',
  links: {
    maltsterid: '123612467659876'
  }
}]
}

Request params: ….

Hops

Add/update hops

POST - api.microbrew.it/hops

name: 'Name of hops'
aa: 2 //Alpha Acid of the hops
origin: http:ontology.microbrew.it/origin/USA // The url to the origin of the hops, this is a optional value
flavor: 'The flavor description of the hops' //Optional value

List hops

GET - api.microbrew.it/hops

Get single hop

GET - api.microbrew.it/hops/:hop

Returns

{
meta: {
  total: 123608,
  returned: 1,
  skip: 0,
  size: 1
},
links: {
  hops.recommendedUse: {
    href: 'http://api.microbrew.it/hops/recommendedusage/:recommendedusageid',
    type: 'recommendedUsage'
   },
  hops.origin: {
   href: 'http://api.microbrew.it/origin/:originid',
   type: 'origin'
  },
},
hops: [{
  id: 'http://microbrew.it/ontology/hops/:hop',
  href: 'http://api.microbrew.it/hops/:hop',
  name: 'Admiral',
  alpha: '5',
  flavour: 'Burnt flavour',
  links: {
    recommendedUsageid : 'http://microbrew.it/ontology/Bittering',
    originid : 'http://microbrew.it/ontology/United_Kingdom'
  }
}]
}

Yeast

Add/update yeast

POST - api.microbrew.it/yeasts

List yeasts

GET - api.microbrew.it/yeasts

Get single yeast

GET - api.microbrew.it/yeasts/:yeast

Other

Other ingredients include fruits, infermentable sugars and other things.

Add a custom footer
Add a custom sidebar
Clone this wiki locally