Skip to content

API Documentation

Jump to bottom Edit New page
Snorre Magnus Davøen edited this page Sep 29, 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

{
  meta: {
    message: "Information about response",
    returned: 1,
    ......
  }
}

All message responses includes a meta object with 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': {
    'message': 'Info about error',
    'code': '0'
  }
}

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/users 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.

Request Parameters

  • username (String) Required
  • password (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
password => mycomplexpass
email => some@email.com
breweryName => My Awesome Brewery
settings: => {}

Response:

{
meta: {
  message: 'The user was successfully added.',
  returned: 1
},
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 same key value-pairs as when adding a new user.

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

Response:

{
meta: {
  message: 'The user was successfully updated.',
  returned: 1
},
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/users/login

Request parameters:

  • id (String) Required
  • password (String) Required'

Example usage

id => myusername
password => mycomplexpass

Response:

{
  "meta":{
    "message": "User successfully logged in.",
    "returned": 1
  },
  "users": [{
    "id": "torbrygg",
    "href":"http://localhost:3000/users/torbrygg",
    "username":"torbrygg",
    "email":"tor@brygg.no",
    "settings":"{}"
    }]
}

User logout

POST - api. microbrew.it/users/logout

Request Parameters:

None

Example Usage

Response:

{
  "meta":{
    "message":"User successfully logged out."
  }
}

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',
aalow => 2 //Lowest range of hops alpha acid,
aahigh => 6 //Highest range of the hops alpha acid
origin => http:ontology.microbrew.it/origin/USA // The url to the origin of the hops, this is a optional value
flavourdescription => 'The flavour description of the hops' //Optional value
flavours => [ "Sweet","Fruity" //List of flavours ]
recommendedusage =>'http://ontology.microbrewi.it/#Bittering' //What the hops is recommended used for. either bittering, aromor or both 
substitutions => [ "http://ontology.microbrew.it/#Warrior",] //A uri list of substitute hops

}]

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: '1223345566678',
  href: 'http://api.microbrew.it/hops/:hop',
  name: 'Admiral',
  aalow: '5',
  aahigh: '7'
  flavour: ["Burnt","Fresh"],
  flavourdecription: 'SOmehting flavour something'
  recommendedusage: 'Bittering'
  substitutions: ["Hefferstuff","Stuff"]
  links: {
    recommendedUsageid : '232342342342342',
    originid : '23423423424234',
    substituesid ["3423423423232","2352452452435345"];
  }
}]
}

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