Marketplace API

This page is focused on providing a complete technical overview of the API. For a set of examples, please go to the example page.

Version 01

The first version of the Marketplace API is focused on providing basic mechanisms for data input and output. It may be a bit rough around the edges.

URLs

This API is a RESTful API, where URLs will be formed (most often) like the following:

Examples

URL formation:

        http://commons.codeforamerica.org/api/v1/[[method]].[[format]]?[[key]]=[[value]]

URL example:

        http://commons.codeforamerica.org/api/v1/node.json?page=3

Authentication

You will need to authenticate in some way if you want to create, update or delete data in the system.

Session/Cookie Based

Session based authentication is a method in which you post your username and password to an endpoint, and you will be given a session name and session ID that can be used for requests that require specific authenticated access (such as creating an Organization). Please see the User Actions below for more in-depth look at the methods.

CURL example

Use the following command to get back the session data. We use the verbose flag just so that you can see what is going on.

          curl -v --data '{"username":"[[your_username]]","password":"[[your_password]]"}' --header "Content-Type:application/json" http://commons.codeforamerica.org/api/v1/user/login

You should recieve an object back that is similar to the following:

          sessid: XXXXXXXXXXXXXXX
          session_name: YYYYYYYYYYYYY
          user: |

These can then be used in a call to create a node within the cookie.

          curl -v --data '{"title":"New Organization","type":"organization"}' --header "Content-Type:application/json" --header "Cookie: [[session_name]]=[[Session_id]]" http://commons.codeforamerica.org/api/v1/node

Output Formatters

The following are the output formatters that are available with the API.

bencode

Bencode is used by BitTorrent.

Example URL:

          http://commons.codeforamerica.org/api/v1/node.bencode

json

JSON is a popular format used to describe Javascript objects.

Example URL:

          http://commons.codeforamerica.org/api/v1/node.json

jsonp

JSONP is similar to JSON but is meant to get around Javascript cross-domain limitations. This format takes an extra argument in the query string, callback, which is a Javascript callback function on your client-side code. You must add the Accept: application/javascript HTTP header (not application/json).

Example URL:

          http://commons.codeforamerica.org/api/v1/node.jsonp?callback=ExampleCallback

php

Output data as a serialized PHP object.

Example URL:

          http://commons.codeforamerica.org/api/v1/node.php

rss

RSS is a popular format for syndicating content like blogs. (seems to be some errors with this format)

Example URL:

          http://commons.codeforamerica.org/api/v1/node.rss

xml

XML is a markup language similar to HTML.

Example URL:

          http://commons.codeforamerica.org/api/v1/node.xml

yaml

YAML is a markup language meant for simplicity. (seems to be always empty)

Example URL:

          http://commons.codeforamerica.org/api/v1/node.yaml

Input Parsers

The following are the output formatters that are available with the API.

application/json

JSON is a popular format used to describe Javascript objects.

Example data:

          
{
  key1: "value1", 
  key2: "value2"
}

application/vnd.php.serialized

Input data as a serialized PHP object.

Example data:

          a:2:{s:4:"key1";s:6:"value1";s:4:"key2";s:6:"value2";}

application/x-www-form-urlencoded

x-www-form-urlencoded is an HTTP specification for sending data with simple URL encoding.

Example data:

          key1=value1&key2=value2

application/x-yaml

YAML is a markup language meant for simplicity.

Example data:

          
key1: value1
key2: value2

multipart/form-data

form-data is an HTTP specification for sending data.

Example data:

          
Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="submit-name"

Larry
--AaB03x
Content-Disposition: form-data; name="files"; filename="file1.txt"
Content-Type: text/plain

... contents of file1.txt ...
--AaB03x--

Limitations

coming soon.

Data Model

Without knowing much about the data model, working with the API will be difficult. The following is a list of entities and fields available on the site. For reference, checkout what Fields and Entities are in Drupal. Note that often the name and description of the data model fields and entities are taken from their user-focused counter parts and may not fully be appropriate for this context.

Data Model: Nodes

Data Model: Nodes

Nodes, often referred to as content, are the building blocks of the application and Drupal in general.

Application

An application is a software project, e.g., CiviCRM, Alfresco, Microsoft Office, etc. It can be either proprietary or open source.

Custom Fields

id	Label	Description	Type
field_application_sdesc	Short Description for Search Results	E.g. A web-based data visualization tool	text
field_application_logo	Logo		image
field_application_rlss	Releases		node_reference
field_application_relapps	Related apps		node_reference
field_application_featurs	Key features		text
field_application_type	Technology Type		taxonomy_term_reference
field_application_creator	Who Created the Application?	start typing the organization name into the field and it should appear below the field. Select it, and it will appear in the box with its Marketplace ID Number, e.g., "New York City Department of Transportation [nid:13334]" If the organization is not yet listed on the Marketplace, it will not appear with its Marketplace ID Number: please click "create organization" button to add it!	node_reference
field_application_vendors	Which Vendors Provide Support?	start typing the vendor name into the field and it should appear below the field. Select it, and it will appear in the box with it's Marketplace ID Number, e.g., "Aquia [nid:217]]" If the vendor is not yet listed on the Marketplace, it will not appear with it's Marketplace ID Number: please click "create organization" button to add it!	node_reference
field_application_hostname	Host name		text
field_application_hosturl	Host URL		link_field
field_application_demourl	Demo URL		link_field
field_application_license	License		taxonomy_term_reference
field_application_rating	Rating	What do you think of the application? Is it easy to use? Is it easy to implement? (Your rating will be aggregated with others).	fivestar
field_application_description	App Description	What does the app do? What should people know about the app?	text_long
field_application_reqs	Software Requirements		taxonomy_term_reference
field_application_deliverymeth	Software Type	Is the software a binary such as a .exe, like MS Word? Is it SaaS (Software as a Service), provided by a hosted or cloud service like Google Apps? Is it an open source scripting language like a PHP app?	taxonomy_term_reference
field_application_civfunction	Primary Civic Function	Don't see a term you need? Add it here	taxonomy_term_reference
field_application_softfunction	Software Function	Don't see a term you need? Add it here	taxonomy_term_reference
field_application_projects	Related Projects		node_reference
field_application_interactions	Add Deployment, Creation, Evaluation, Support	Please Click "Create Interaction" When done, it will show up in the field above.	node_reference
field_application_screenshots	Screenshots		image
field_application_tutors	Videos		media
field_application_homepage	App Homepage	Enter the URL of the application homepage where people can go to find more information	link_field
field_project_resulted	Project this app resulted from		node_reference
field_application_stds	Standards Implemented		node_reference
field_application_tags	Tags	Separate tags w/ a comma.	taxonomy_term_reference

Interaction

Custom Fields

id	Label	Description	Type
field_interaction_organization	Who	What organization or company is involved in this story? Start typing to choose from existing options, or click "Create Organization" to create a new one.	node_reference
field_interaction_application	With what	The Application involved in this story -- start typing to choose from a list, or click "Create Application" to add a new one.	node_reference
field_interaction_type	Did what	What did they do?	taxonomy_term_reference
field_interaction_project	This field doesn't work yet. skip it. Sorry it's here.		node_reference
field_interaction_date	When		datestamp
field_url	Link(s)	Please provide a complete url, e.g. http://www.example.com	link_field
field_interaction_content	Details	What happened? Optionally, describe this story in a bit more detail.	text_long

Organization

An Organization is an operating entity, of type = government, nonprofit/ngo, company. Organizations can play a number of roles, including technology user, service provider, etc. And they interact with technologies ("Apps" in our nomenclature) in a number of ways, via "Interactions." The Organization data type deprecates the Agency and Vendor types.

Custom Fields

id	Label	Description	Type
field_organization_decs	Description		text_long
field_organization_type	What kind of Organization is it?		taxonomy_term_reference
field_organization_address	Street address		addressfield
field_organization_logo	Logo		image
field_organization_link	Website		link_field
field_organization_abbr	Abbreviation	e.g., DPW or DoITT	text
field_organization_wiki	Wikipedia Article	Enter the URL to the Wikipedia article on this organization, if one exists.	link_field
field_organization_abudget	Annual budget (in USD)		number_decimal
field_organization_employees	Number of Employees		number_integer
field_organization_pbudget	Typical project budget (in USD)		number_decimal
field_organization_interactions	Deployments, Evaluations and other interactions with apps	Has this organization evaluated, deployed or contributed to Apps in the marketplace? If so, link them up above. Please Click "Create Interaction" When done, it will show up in the field above.	node_reference
field_organization_services	for Vendors: What Application Services do they provide?		taxonomy_term_reference
field_organization	Related Civic Functions	Select all that apply.	taxonomy_term_reference
field_organization_members	Who works there?	select all that apply (hold control on pc, command on mac)	user_reference
field_organization_branch	Branch of Government		taxonomy_term_reference
field_organization_phone	Phone		phone_number
field_organization_coords	Coordinates		geofield
field_organization_apps_created	Apps this organization created		node_reference
field_vending_apps	Apps this organization provides support / services for		node_reference
field_organization_tags	Tags	Separate tags w/ a comma.	taxonomy_term_reference

Searching

Utilizing the Views methods as described below, you can find specific content. Please see the Views section to get a general description of using the Searching API.

Application API

Provides a view of Application nodes specifically for the public API.

Identifier: application_api
Base table: node

Field View

Field view of Applications. Use this display for simple objects.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/application_api.json?display_id=field_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Search Terms	keywords	no
Civic Function (Taxonomy Term ID)	civicfunction	no
License (Taxonomy Term ID)	application_license	no
Key Features (String)	key_features	no

Node View

Provides same as Field View but renders full node object.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/application_api.json?display_id=node_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Search Terms	keywords	no
Civic Function (Taxonomy Term ID)	civicfunction	no
License (Taxonomy Term ID)	application_license	no
Key Features (String)	key_features	no

Interaction API

Provides a view of Interaction nodes specifically for the public API.

Identifier: interaction_api
Base table: node

Field View

Interaction nodes output as simple fields.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/interaction_api.json?display_id=field_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Keyword Search (String)	keywords	no
Interaction Type (Taxonomy Term ID)	interaction_type	no
Organization (Node ID)	organization	no
Application (Node ID)	application	no

Node View

Search interactions and output data as full nodes.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/interaction_api.json?display_id=node_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Keyword Search (String)	keywords	no
Interaction Type (Taxonomy Term ID)	interaction_type	no
Organization (Node ID)	organization	no
Application (Node ID)	application	no

Organization API

Provides a view of Organization nodes specifically for the public API.

Identifier: organization_api
Base table: node

Field View

Organizations as simple fields.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/organization_api.json?display_id=field_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Search Terms (String)	keywords	no
Interaction (Node ID)	interactions	no
Application Services (Taxonomy Term ID)	services	no
Kind of Organization? (Taxonomy Term ID)	organization_type	no
State (2 Letter)	address_administrative_area_state	no
City	address_locality_city	no

Node View

Renders full node for searching Organizations.

Examples

Search with filters:

        http://commons.codeforamerica.org/api/v1/views/organization_api.json?display_id=node_view&filters[:id1]=:value1&filters[:id2]=:value2

Filters

Name	Identifier	Required
Search Terms (String)	keywords	no
Interaction (Node ID)	interactions	no
Application Services (Taxonomy Term ID)	services	no
Kind of Organization? (Taxonomy Term ID)	organization_type	no
State (2 Letter)	address_administrative_area_state	no
City	address_locality_city	no

Resources

Resource, or methods, are the specific RESTful API calls for manipulating data.

Resource: Comments

Resource: Comments

Comments are user supplied data that are attached to content, like nodes.

Comment Operations

Basic operations for the Comment objects.

Create Comments

Use this method to create a specific comment.

Method: POST

Arguments

Key	Type	Description	Required	Source
comment	array	The comment object	yes	post body

Examples

CURL:

        curl -v -X POST --data '{"title":"comment title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/comment

Retrieve Comments

Use this method to retrieve a specific comment.

Method: GET

Arguments

Key	Type	Description	Required	Source
cid	int	The cid of the comment to retrieve.	yes	path

Examples

CURL:

        curl -v  http://commons.codeforamerica.org/api/v1/comment/[[cid]].json

Update Comment

Use this method to update a specific comment.

Method: PUT

Arguments

Key	Type	Description	Required	Source
cid	int	The unique identifier for this comment.	yes	path
data	array	The comment object with updated information	yes	post body

Examples

CURL:

        curl -v -X PUT --data '{"title":"new title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/comment/[[cid]]

Delete Comment

Use this method to delete a specific comment.

Method: DELETE

Arguments

Key	Type	Description	Required	Source
cid	int	The id of the comment to delete	yes	path

Examples

CURL:

        curl -v -X DELETE --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/comment/[[cid]]

Search Comment

Use this method to search comments.

Method: GET

Arguments

Key	Type	Description	Required	Source
page	int	The zero-based index of the page to get, defaults to 0.	no	param
fields	string	The fields to get.	no	param
parameters	array	Parameters	no	param
pagesize	init	Number of records to get per page.	no	param

Examples

CURL:

        curl -v http://commons.codeforamerica.org/api/v1/comment.json

CURL (with parameters):

        curl -v http://commons.codeforamerica.org/api/v1/comment.json?parameters%5Bcid%5D=[[cid]]

Comment Actions

Actions for the Comment objects.

Count Comments per Node

Returns the number of comments are on a single node.

Method: GET

Arguments

Key	Type	Description	Required	Source
nid	int	The node id to count all comments.	yes	data

Examples

CURL:

        curl  -X GET -v --data '{"nid":"1234"}' http://commons.codeforamerica.org/api/v1/comment/countAll

Count New Comments per Node

Returns the number of new comments are on a single node, given a timestamp.

Method: GET

Arguments

Key	Type	Description	Required	Source
nid	int	The node id to load comments for.	yes	data
since	int	Timestamp to count from (defaults to time of last user acces to node).	no	data

Examples

CURL:

        curl  -X GET -v --data '{"nid":"1234", "since":"123456789"}' http://commons.codeforamerica.org/api/v1/comment/countNew

Resource: Nodes (Content)

Resource: Nodes (Content)

Nodes are the basic content objects in the system.

Node Operations

Basic operations for the Node objects.

Create Node

Use this method to create a specific node.

Method: POST

Arguments

Key	Type	Description	Required	Source
node	array	The node data to create	yes	post body

Examples

CURL:

        curl -v -X POST --data '{"title":"node title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/node

Retrieve Nodes

Use this endpoint to retrieve a specific node.

Method: GET

Arguments

Key	Type	Description	Required	Source
nid	int	The nid of the node to get	yes	path

Examples

CURL:

        curl -v -X GET http://commons.codeforamerica.org/api/v1/node/[[nid]].json

Update Node

Use this method to update a specific node.

Method: PUT

Arguments

Key	Type	Description	Required	Source
nid	int	The nid of the node to get	yes	path
node	array	The node data to update	yes	post body

Examples

CURL:

        curl -v -X PUT --data '{"title":"new title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/node/[[nid]]

Delete Node

Use this method to delete a specific comment.

Method: DELETE

Arguments

Key	Type	Description	Required	Source
nid	int		yes	path

Examples

CURL:

        curl -v -X DELETE --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/node/[[nid]]

Search Nodes

Use this method to search nodes.

Method: GET

Arguments

Key	Type	Description	Required	Source
page	int	The zero-based index of the page to get, defaults to 0.	no	param
fields	string	The fields to get.	no	param
parameters	array	Parameters array	no	param
pagesize	init	Number of records to get per page.	no	param

Examples

CURL:

        curl -v -X GET http://commons.codeforamerica.org/api/v1/node.json

CURL (with parameters):

        curl -v -X GET http://commons.codeforamerica.org/api/v1/node.json?parameters%5Bcid%5D=[[cid]]

Node Relationships

Retrieve objects that are related to nodes.

Files Attached to Node

Use this method to get files that are associated with a node.

Method: GET

Arguments

Key	Type	Description	Required	Source
nid	int	The nid of the node whose files we are getting	yes	path
file_contents	int	To return file contents or not.	no	path
image_styles	int	To return image styles or not.	yes	path

Examples

CURL:

        curl -v -X GET --data '{"nid":"1234"}' http://commons.codeforamerica.org/api/v1/node.json

New Comments Attached to Node

Use this method to get new comments associated with a node.

Method: GET

Arguments

Key	Type	Description	Required	Source
nid	int	The node id to load comments for.	yes	path
count	int	Number of comments to load.	no	param
offset	int	If count is set to non-zero value, you can pass also non-zero value for start. For example to get comments from 5 to 15, pass count=10 and start=5.	no	param

Examples

CURL:

        curl -v -X GET http://commons.codeforamerica.org/api/v1/node/[[nid]].json?count=3

Resource: Taxonomy Terms

Resource: Taxonomy Terms

Taxonomies are ways of grouping objects, like nodes, and the terms are the specific category terms.

Term Operations

Basic operations for Taxonomy Term objects.

Create Term

Use this method to create a specific Taxonomy Term.

Method: POST

Arguments

Key	Type	Description	Required	Source
term	array	The taxonomy term object to create	yes	post body

Examples

CURL (Session auth):

        curl -v -X POST --data '{"title":"new title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/taxonomy_term

Retrieve Term

Use this endpoint to retrieve a specific Term.

Method: GET

Arguments

Key	Type	Description	Required	Source
tid	int	The tid of the taxonomy term to get	yes	path

Examples

CURL:

        curl -v http://commons.codeforamerica.org/api/v1/taxonomy_term/[[tid]].json

Update Term

Use this method to update a specific term.

Method: PUT

Arguments

Key	Type	Description	Required	Source
tid	int	The unique identifier for this taxonomy term.	yes	path
term	array	The taxonomy term data to update	yes	post body

Examples

CURL (Session auth):

        curl -v -X PUT --data '{"title":"new title"}' --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/taxonomy_term/[[tid]]

Delete Term

Use this method to delete a specific term.

Method: DELETE

Arguments

Key	Type	Description	Required	Source
tid	int		yes	path

Examples

CURL (Session auth):

        curl -v -X DELETE --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/taxonomy_term/[[tid]]

Search Terms

Use this method to search Terms.

Method: GET

Arguments

Key	Type	Description	Required	Source
page	int	The zero-based index of the page to get, defaults to 0.	no	param
fields	string	The fields to get.	no	param
parameters	array	Parameters	no	param
pagesize	init	Number of records to get per page.	no	param

Examples

CURL:

        curl -v http://commons.codeforamerica.org/api/v1/taxonomy_term.json

CURL with parameters:

        curl -v http://commons.codeforamerica.org/api/v1/taxonomy_term.json?parameters%5Bvid%5D=[[vid]]

Term Actions

Actions for the Term objects.

Nodes with Term

Use this method to get all nodes with specific Term.

Method: GET

Arguments

Key	Type	Description	Required	Source
tid	string	The vocabulary ids to retrieve, separated by comma.	yes	data
pager	int	Whether the nodes are to be used with a pager (the case on most Drupal pages) or not (in an XML feed, for example).	no	data
limit	int	Maximum number of nodes to find.	no	data
order	int	The order clause for the query that retrieve the nodes.	no	data

Examples

CURL:

        curl -v http://commons.codeforamerica.org/api/v1/taxonomy_term/selectNodes.json?tid=[[tid]]

Resource: Views

Resource: Views

Views are queries of data as defined in configuration.

Views Operations

Basic operations on Views.

Search Views

Use this method to search Views.

Method: GET

Arguments

Key	Type	Description	Required	Source
view_name	string	The name of the view to get.	yes	path
display_id	string	The display ID of the view to get.	no	param
args	array	A list of arguments to pass to the view.	no	param
offset	int	The number of the entry for the page begin with.	no	param
limit	int	The total number of entries to list.	no	param
theme_output	bool	Whether to return the raw data results or style the results.	no	param
filters	array	A list of filters to pass to the view. These are defined by the exposed filters on your view. Example call: `/views/your_view?filters[nid]=12345`	no	param

Examples

CURL:

        curl -v --data http://commons.codeforamerica.org/api/v1/views/[[view-name]].json

Resource: User

Resource: User

User methods.

User Actions

User actions like logging in and logging out.

User Login

Use this method to login into the site with a username and password. you will recieve a session name and session ID that can then be used within a cookie to make requests that require authentication.

Method: POST

Arguments

Key	Type	Description	Required	Source
username	string	A valid username	yes	data
password	string	A valid password	yes	data

Examples

CURL:

        curl -v --data '{"username":"[[your_username]]","password":"[[your_password]]"}' --header "Content-Type:application/json" http://commons.codeforamerica.org/api/v1/user/login

User Logout

Logout a user, given the session.

Method: POST

Examples

CURL:

        curl -v --header "Cookie: [[session_name]]=[[session_id]]" http://commons.codeforamerica.org/api/v1/user/logout

You are here

Version 01

URLs

Authentication

Session/Cookie Based

Output Formatters

Input Parsers

Limitations

Data Model

Data Model: Nodes

Application

Interaction

Organization

Searching

Application API

Field View

Node View

Interaction API

Field View

Node View

Organization API

Field View

Node View

Resources

Resource: Comments

Comment Operations

Create Comments

Retrieve Comments

Update Comment

Delete Comment

Search Comment

Comment Actions

Count Comments per Node

Count New Comments per Node

Resource: Nodes (Content)

Node Operations

Create Node

Retrieve Nodes

Update Node

Delete Node

Search Nodes

Node Relationships

Files Attached to Node

New Comments Attached to Node

Resource: Taxonomy Terms

Term Operations

Create Term

Retrieve Term

Update Term

Delete Term

Search Terms

Term Actions

Nodes with Term

Resource: Views

Views Operations

Search Views

Resource: User

User Actions

User Login

User Logout