Under Construction: We're in Beta You should help us Build: add an app add an org

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

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

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

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

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

Limitations

coming soon.

Data Model

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
idLabelDescriptionType
field_application_sdescShort Description for Search ResultsE.g. A web-based data visualization tool text
field_application_logoLogoimage
field_application_rlssReleasesnode_reference
field_application_relappsRelated appsnode_reference
field_application_featursKey featurestext
field_application_typeTechnology Typetaxonomy_term_reference
field_application_creatorWho 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_vendorsWhich 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_hostnameHost nametext
field_application_hosturlHost URLlink_field
field_application_demourlDemo URLlink_field
field_application_licenseLicensetaxonomy_term_reference
field_application_ratingRatingWhat 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_descriptionApp DescriptionWhat does the app do? What should people know about the app?text_long
field_application_reqsSoftware Requirementstaxonomy_term_reference
field_application_deliverymethSoftware TypeIs 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_civfunctionPrimary Civic FunctionDon't see a term you need? Add it heretaxonomy_term_reference
field_application_softfunctionSoftware FunctionDon't see a term you need? Add it heretaxonomy_term_reference
field_application_projectsRelated Projectsnode_reference
field_application_interactionsAdd Deployment, Creation, Evaluation, SupportPlease Click "Create Interaction" When done, it will show up in the field above.node_reference
field_application_screenshotsScreenshotsimage
field_application_tutorsVideosmedia
field_application_homepageApp HomepageEnter the URL of the application homepage where people can go to find more informationlink_field
field_project_resultedProject this app resulted fromnode_reference
field_application_stdsStandards Implementednode_reference
field_application_tagsTagsSeparate tags w/ a comma.taxonomy_term_reference

Interaction

Custom Fields
idLabelDescriptionType
field_interaction_organizationWhoWhat 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_applicationWith whatThe 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_typeDid whatWhat did they do?taxonomy_term_reference
field_interaction_projectThis field doesn't work yet. skip it. Sorry it's here. node_reference
field_interaction_dateWhendatestamp
field_urlLink(s)Please provide a complete url, e.g. http://www.example.comlink_field
field_interaction_contentDetailsWhat 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
idLabelDescriptionType
field_organization_decsDescriptiontext_long
field_organization_typeWhat kind of Organization is it?taxonomy_term_reference
field_organization_addressStreet addressaddressfield
field_organization_logoLogoimage
field_organization_linkWebsitelink_field
field_organization_abbrAbbreviatione.g., DPW or DoITTtext
field_organization_wikiWikipedia ArticleEnter the URL to the Wikipedia article on this organization, if one exists.link_field
field_organization_abudgetAnnual budget (in USD)number_decimal
field_organization_employeesNumber of Employeesnumber_integer
field_organization_pbudgetTypical project budget (in USD)number_decimal
field_organization_interactionsDeployments, Evaluations and other interactions with appsHas 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_servicesfor Vendors: What Application Services do they provide?taxonomy_term_reference
field_organizationRelated Civic FunctionsSelect all that apply.taxonomy_term_reference
field_organization_membersWho works there?select all that apply (hold control on pc, command on mac)user_reference
field_organization_branchBranch of Governmenttaxonomy_term_reference
field_organization_phonePhonephone_number
field_organization_coordsCoordinatesgeofield
field_organization_apps_createdApps this organization creatednode_reference
field_vending_appsApps this organization provides support / services fornode_reference
field_organization_tagsTagsSeparate tags w/ a comma.taxonomy_term_reference
Searching

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
NameIdentifierRequired
Search Termskeywordsno
Civic Function (Taxonomy Term ID)civicfunctionno
License (Taxonomy Term ID)application_licenseno
Key Features (String)key_featuresno
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
NameIdentifierRequired
Search Termskeywordsno
Civic Function (Taxonomy Term ID)civicfunctionno
License (Taxonomy Term ID)application_licenseno
Key Features (String)key_featuresno

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
NameIdentifierRequired
Keyword Search (String)keywordsno
Interaction Type (Taxonomy Term ID)interaction_typeno
Organization (Node ID)organizationno
Application (Node ID)applicationno
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
NameIdentifierRequired
Keyword Search (String)keywordsno
Interaction Type (Taxonomy Term ID)interaction_typeno
Organization (Node ID)organizationno
Application (Node ID)applicationno

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
NameIdentifierRequired
Search Terms (String)keywordsno
Interaction (Node ID)interactionsno
Application Services (Taxonomy Term ID)servicesno
Kind of Organization? (Taxonomy Term ID)organization_typeno
State (2 Letter)address_administrative_area_stateno
Cityaddress_locality_cityno
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
NameIdentifierRequired
Search Terms (String)keywordsno
Interaction (Node ID)interactionsno
Application Services (Taxonomy Term ID)servicesno
Kind of Organization? (Taxonomy Term ID)organization_typeno
State (2 Letter)address_administrative_area_stateno
Cityaddress_locality_cityno
Resources

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
KeyTypeDescriptionRequiredSource
commentarrayThe comment objectyespost 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
KeyTypeDescriptionRequiredSource
cidintThe cid of the comment to retrieve.yespath
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
KeyTypeDescriptionRequiredSource
cidintThe unique identifier for this comment.yespath
dataarrayThe comment object with updated informationyespost 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
KeyTypeDescriptionRequiredSource
cidintThe id of the comment to deleteyespath
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
KeyTypeDescriptionRequiredSource
pageintThe zero-based index of the page to get, defaults to 0.noparam
fieldsstringThe fields to get.noparam
parametersarrayParametersnoparam
pagesizeinitNumber of records to get per page.noparam
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
KeyTypeDescriptionRequiredSource
nidintThe node id to count all comments.yesdata
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
KeyTypeDescriptionRequiredSource
nidintThe node id to load comments for.yesdata
sinceintTimestamp to count from (defaults to time of last user acces to node).nodata
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
KeyTypeDescriptionRequiredSource
nodearrayThe node data to createyespost 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
KeyTypeDescriptionRequiredSource
nidintThe nid of the node to getyespath
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
KeyTypeDescriptionRequiredSource
nidintThe nid of the node to getyespath
nodearrayThe node data to updateyespost 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
KeyTypeDescriptionRequiredSource
nidintyespath
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
KeyTypeDescriptionRequiredSource
pageintThe zero-based index of the page to get, defaults to 0.noparam
fieldsstringThe fields to get.noparam
parametersarrayParameters arraynoparam
pagesizeinitNumber of records to get per page.noparam
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
KeyTypeDescriptionRequiredSource
nidintThe nid of the node whose files we are gettingyespath
file_contentsintTo return file contents or not.nopath
image_stylesintTo return image styles or not.yespath
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
KeyTypeDescriptionRequiredSource
nidintThe node id to load comments for.yespath
countintNumber of comments to load.noparam
offsetintIf 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.noparam
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
KeyTypeDescriptionRequiredSource
termarrayThe taxonomy term object to createyespost 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
KeyTypeDescriptionRequiredSource
tidintThe tid of the taxonomy term to getyespath
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
KeyTypeDescriptionRequiredSource
tidintThe unique identifier for this taxonomy term.yespath
termarrayThe taxonomy term data to updateyespost 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
KeyTypeDescriptionRequiredSource
tidintyespath
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
KeyTypeDescriptionRequiredSource
pageintThe zero-based index of the page to get, defaults to 0.noparam
fieldsstringThe fields to get.noparam
parametersarrayParametersnoparam
pagesizeinitNumber of records to get per page.noparam
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
KeyTypeDescriptionRequiredSource
tidstringThe vocabulary ids to retrieve, separated by comma.yesdata
pagerintWhether the nodes are to be used with a pager (the case on most Drupal pages) or not (in an XML feed, for example).nodata
limitintMaximum number of nodes to find.nodata
orderintThe order clause for the query that retrieve the nodes.nodata
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
KeyTypeDescriptionRequiredSource
view_namestringThe name of the view to get.yespath
display_idstringThe display ID of the view to get.noparam
argsarrayA list of arguments to pass to the view.noparam
offsetintThe number of the entry for the page begin with.noparam
limitintThe total number of entries to list.noparam
theme_outputboolWhether to return the raw data results or style the results.noparam
filtersarrayA 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]=12345noparam
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
KeyTypeDescriptionRequiredSource
usernamestringA valid usernameyesdata
passwordstringA valid passwordyesdata
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