[seagrant-dev] Draft API spec

Kennric kennric at osuosl.org
Tue Jul 29 19:23:56 UTC 2014


This is a rough draft of the API spec, subject to change as features are 
clarified. This document is available here:

https://docs.google.com/a/osuosl.org/document/d/1NsusA6QEYzi7jJOC5OnxRfoSRJEbq4bPocbRLcr5OIY/edit

Please use the Google doc to add comments, but please do not modify the draft 
itself. If you don't have access to the Google doc, please let me know.

We will include this in the official project documentation tree as soon as that 
is established.

Thanks,
Ken

---------

API
===

Format
------

Responses will be returned in standard JSON format. An attempt will be made to 
keep the structure simple.

Errors
------

Error records will be returned in every message, and will consist of a 
dictionary containing the error status, error name, error text and error 
level. The status field will indicate the presence of an error condition, and 
should be checked before attempting to process the rest of the response.

ex.: error: {error_status: true, error_name: 'not_found_error', error_text: 
'product with id=232 could not be found', error_level: 10}

Extended Fields
---------------

To allow for future expandability, a dictionary call 'ext' will be included 
with every response. This dictionary will either contain no records, or will 
contain additional first-class records that were not included in the original 
specification. For instance, if a new attribute "color" is later added to the 
product response, it can be included in the extended attributes array. 
Applications can choose to discover/use these new fields or ignore them without 
effecting backwards compatibility. Response validation should include the 
presence of ext, but not its contents.


Endpoints
---------

*/products*
Return a dictionary containing a record for every product in the database.The 
product id is the record key. This data is unlikely to change frequently, it 
should be in long-term storage on the device and refreshed periodically.

{
	error: {error_status: bool, error_name: text, error_text: text, 
error_level},
    <product_id>: { 
		name: text
		variety: text
		alt_name: text
		description: text
		region: text
		season: text
		in_season: bool
		market_price: text
		freshness: text
		form: text
		link: url
		image: url
		story: int
		created: datetime
		modified: datetime
		ext: {attribute: value, attribute: value...}	
	},
	<product_id>: {...},
	...
}


*/products/<id>* 
Returns a single product record identified by <id>. This may be useful for 
selectively refreshing the local master list of products fetched by /products.

{
	error: {error_status: bool, error_name: text, error_text: text, 
error_level},
	id: int
	name: text
	variety: text
	alt_name: text
	description: text
	region: text
	season: text
	in_season: bool
	market_price: text
	freshness: text
	form: text
	link: url
	image: url
	story: int
	created: datetime
	modified: datetime
	ext: {attribute: value, attribute: value...}			
}
	

*/products/describe*
Returns a description of the fields in a product record. These should 
correspond to internal docstrings, which in turn should be extracted into the 
master project documentation.

{
	endpoint_description: "text describing the endpoint"
	id: "text describing this field"
	...
}


*/vendors*
Return a dictionary containing a record for each vendor in the database. The 
vendor id is the record key. Each vendor record also contains a dictionary of 
products carried by this vendor. This data is likely to change more often, and 
should be cached locally but refreshed for specific products or locations 
whenever possible.
{
	error: {error_status: bool, error_name: text, error_text: text, 
error_level},
	<vendor_id>: {
		name: text
		status: bool, null
		description: text
		gps_location: coords
		street: text
		city: text
		state: text
		zip: text
		location_description: text
		contact_name: text
		phone: text
		website: url
		email: email
		story: int
		ext: {attribute: value, attribute: value...}
		created: datetime
		updated: datetime
		products: {
			<product_id>: {name: text},
			<product_id>: {name: text},...
		}
	},
	<vendor_id>: {...},
	...
}


*/vendors/<id>*
Returns a single vendor record identified by <id>. This should be used to fetch 
data whenever a specific vendor id is known.

{
	id: int
	name: text
	status: bool, null
	description: text
	gps_location: coords
	street: text
	city: text
	state: text
	zip: text
	location_description: text
	contact_name: text
	phone: text
	website: url
	email: email
	story: int
	ext: {attribute: value, attribute: value...}
	created: datetime
	updated: datetime
	products: [
			{id: int, name: text},
			{id: int, name: text},...
			]
}


*/vendors/describe*
Returns a description of the fields in a vendor record. These should correspond 
to internal docstrings, which in turn should be extracted into the master 
project documentation.

{
	id: (text describing this field)
	...
}


*/stories/<id>*
Returns a story record identified by <id>.

{
	story: "rich text"
}


*/images/<id>*
Returns an image record identified by <id>. Alternatively, this could return 
the image data itself as content-type image rather than json.

{
	image: "url to image"
	caption: "text"
}


*/vendors/product/<id>*
Returns a dictionary of vendors that carry a product identified by <id>. The 
records are identical to those returned by /vendors/<id>, but filtered by the 
product id.


*/nearby/?location=<coords>*
Returns nearby available vendors. Vendor records are as defined above, 
including the products array.



Additional parameters
---------------------

These parameters can be added to any endpoint request

*location=<coords>*
This parameter will cause the results to be sorted by proximity, closest items 
first. This parameter will be ignored with the /stories endpoint.

ex.: http://whatsfresh.org/vendors?location=4928472x897982


*limit=<int>*
This parameter will limit the number of records returned to <int>. In 
combination with the location parameter, it can be used to return the 5 
nearest vendors selling tuna:

http://whatsfresh.org/vendors/product/<tuna_id>?location=4928472x897982&limit=5


More information about the seagrant-dev mailing list