My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
Api  
API for the Online Co-op Software
Featured
Updated Feb 4, 2010 by pau...@gmail.com

Introduction

The software provides a number of Javascript/JSON-based hooks into the system to retrieve data. This page outlines those functions.

URIs in this Document

These URI's are based on the root of where the software is hosted from. In the case of the West Michigan Co-op, that's the root, so if the URI was /exampleURI, the full URL would be http://www.westmichigancoop.com/exampleURI.

You would replace that domain name with your domain name, and if you host this software from a sub-directory, you would add that sub-directory as well.

URI's end in '.json', even when specifying a callback, when the desired result is either a JSON object, or a JSON object wrapped in a callback function.

URI's end in '.rss' when the desired result is an RSS (version 2) feed.

As yet, there are no documented API functions that add or modify data on the Co-op. We currently only support reads - getting producer information, product information, and delivery cycle information. Anything you can read on the site, but would need to screen-scrape, we are trying to provide in a programmer-friendly format.

Specifying Parameters

Parameters are specified with the format parameter-name:parameter-value. Both the names and values should be URL Encoded, so that a ':' in a name or value isn't confused by the server for the ':' delimiter between the name and value.

Multiple parameters are separated by '/'. Two examples:

  1. http://www.westmichigancoop.com/deliveries/current/callback:callbackFunction.json
  2. This calls the function '/deliveries/current' with a parameter 'callback' equal to 'callbackFunction'. That will yeild the JSON object wrapped in 'callbackFunction();'
  3. http://www.westmichigancoop.com/products/search/name:Bacon/from:Creswick.json
  4. This calls the function'/products/search' with parameters 'name' equal to 'Bacon' and 'from' equal to Creswick. It will return only the JSON object; no callback function.

Note that the callback parameter can be specified for any JSON request. That way, you can create a <script> tag to pull data across domains.

Supported Functions

Product Search

  • URI: /products/search
  • Use it to:
  • Acquire an array of JSON objects that are data for products currently listed on the site.
  • Parameters:
    • name: Creates a LIKE %...% based query that matches the product name.
    • from: Creates a LIKE %...% based query that matches the producer's business name.
    • desc: Creates a LIKE %...% based query that matches the product description.
    • product_name: Exact match query on the product name.
    • Member.business_name: Exact match query on the producer's business name.
    • unit_price: Exact match query on the product's price (a range-based parameter is not yet available)
    • limit: The maximum number of products to return. By default, no limit (all products that match query parameters).
    • page: In conjunction with limit, gets the specified page of results. i.e. if limit is 10 and page is 2, this will return products 11 - 20 that match the query. If page is specified without limit, limit is automatically set to 25.
    • order: The field to order results by. Note that you can also pass ' ASC' or ' DESC' in the value of this parameter to specify ascending or descending - but you'll need to URL encode so that it doesn't choke on the space. So to get results in reverse alphabetical by product name, you would say 'order:Product.product_name%20DESC'.
Multiple query parameters result in an AND - we currently do not have OR based queries.
Example: http://www.westmichigancoop.com/products/search/name:Bacon/from:Creswick.json
Returns: an array of Product objects (outlined below) that have 'Bacon' in the name AND 'Creswick' in the business name.
Note that for historical (read: old database) reasons, the 'description' of an item is stored in a field called 'detailed_notes'.
There are other parameters that you can use for exact matches: any database field that is returned in the query can be used to match or order results. Note that as a shortcut, exact matches for product_name and unit_price do not include 'Product.' in front - but they can, and it's perfectly valid. Each product object essentially looks like the following:
{
  Product: {
    product_id: 1234,
    product_name: 'Bacon',
    unit_price: '9',
    pricing_unit: 'pound',
    ordering_unit: 'package',
    random_weight: '1',
    maximum_weight: '2',
    minimum_weight: '.5',
    created: 'DATETIME',
    modified: 'DATETIME',
    detailed_notes: "Bacon is delicious."
  },
  Orderable: {
    id: 4563,
    inventory_left: 23
  },
  Member: {
    business_name: 'Creswick Farms'
  }
}
There will be other fields, but this covers the basics of what you'd need. You can always use a JSON inspector to look at some more of the fields you'll get - in general you get quite a lot!
You can also use this URL on the main site - if you drop the .json, you will get a search page in your browser that shows you what a shopper would see searching with those parameters. Try the example url, minus the JSON:
http://www.westmichigancoop.com/products/search/name:Bacon/from:Creswick

Delivery Cycle Information

  • URI: /deliveries/current
  • Use it to:
  • Get a JSON object containing data about the current delivery cycle dates and times.
  • Parameters:
  • None, save the callback parameter available for every JSON function.
Example: http://www.westmichigancoop.com/deliveries/current/callback:my_function.json
Returns: (a direct copy of the current cycle info as of 3/20/2009)
my_function({
  "Delivery": {
    "delivery_id":"67",
    "open":"1",
    "edit_open":"2009-03-01 00:00:00",
    "order_open":"2009-03-07 00:00:00",
    "delivery_open":"2009-03-25 17:15:00",
    "order_closed":"2009-03-14 00:00:00",
    "msg_all":"",
    "msg_bottom":"",
    "special_order":"0",
    "delivery_closed":"2009-03-25 20:00:00",
    "pickup_open":"2009-03-25 17:45:00",
    "pickup_closed":"2009-03-25 20:00:00"
  }
});
Powered by Google Project Hosting