Overview and Developer's Guide

The ProgrammableWeb API gives you a simple and structured way to access the powerful registry and repository capabilities of ProgrammableWeb. This API for APIs lets you programmaticly search and retrieve APIs, mashups, member profiles and other data from our catalog. Our write capabilities let you dynamically add new content as well as comment on existing entries.

Because our API is based on open standards including XML, RSS, OpenSearch and the Atom Publishing Protocol, you can get up to speed quickly and we work well with the existing tools and technologies you already know. (And if you're familiar with Google's GData APIs you've got an even better head start.)

Getting Started

Getting started with the ProgrammableWeb API is easy, just follow these steps:

Sign-up for a ProgrammableWeb user account
Request a developer key (make sure to give us your PW username)
Read the rest of this overview
Start coding

Note that our developer program is in beta and we expect some changes to the API during this period. Support questions are welcome in our forums and via email at support@programmableweb.com.

Searching APIs using categories and tags
Searching APIs

Searching and retrieving Mashups
Searching and retrieving Widgets
Searching and retrieving Members

Retrieve a specific Member

Adding New Entries

Adding a Mashup or Feed
Adding a Widget
Adding an API
Modifying an API
Adding a Comment

Audience

This guide is intended for programmers who want to access ProgrammableWeb data. This API allows you to build on top of our platform and leverage our database of APIs, mashups, and other resources directly into your own tools and applcations. Use the API to integrate on-demand registry and repository functionality into any service.

If you can submit REST-like HTTP requests and know what to do with results that are returned, you will be able to use the ProgrammableWeb API. Examples with explanations are provided.

For ProgrammableWeb API reference information, see the reference guide.

Searching and retrieving APIs

The ProgrammableWeb API provides a variety of mechanisms for finding and retrieving data about APIs. For example you can retrieve APIs by category, tag, or name. For a given API you can request a feed of that APIs mashups, related links or user comments.

As a simple example: to retrieve the list of APIs in category Mapping, send an HTTP GET request to the following URL

http://api.programmableweb.com/apis/-/Mapping?apikey=123

The response to this GET request will be an HTTP 200 status code and an OpenSearch compatible feed containing the first set of APIs in the category 'Mapping'.

The OpenSearch compatible feed is an Atom Feed document. All timestamps conform to RFC 3339. For example, 2008-08-21T08:46:14Z is a valid RFC 3339 date/time. Feeds are regularly validated to ensure that improvements do not break compatibility with proper Atom parsers.

NOTE: You will need to supply your own developer key anywhere you see the parameter apikey=123

Each entry in the returned feed provides details on a single matching API from our directory

<entry>
        <id>http://www.programmableweb.com/api/google-maps</id>
        <title type="text">Google Maps</title> 
        <link href="http://www.programmableweb.com/api/google-maps"></link>
        <author>
                <name></name>
        </author>
        <summary type="html">Mapping services</summary>
        <content type="application/xml">
                <pw:api xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/">
                        <rating>4.2</rating>
                        <name>Google Maps</name>
                        <label>Google Maps</label>
                        <description>Mapping services</description>

... additional elements here -- see the Reference Guide for details

                </pw:api>
        </content>
        <updated>2005-12-05T05:52:02Z</updated>
</entry>

Searching for APIs

The ProgrammableWeb API lets you search for APIs that meet specific criteria by using a combination of feed parameters or filters. The base search query for APIs is:

http://api.programmableweb.com/apis?apikey=123

The following table outlines some of the most commonly used parameters:

Parameter	Description
alt	Format of data returned. Either atom (default) or json.
/-/category	The category and tags used to classify the given APIs. The first parameter if capitalized is assumed to be a category, otherwise is considered a 'tag' (each API is assigned to a single taxonomic category but can have multiple tags). A combination of both can be used such as '/-/Mapping/photo' which returns all APIs in the Mapping category that are also tagged with the keyword 'photo'.
maxdays	The maximum number of days before today to search for recently published APIs. Uses the Date Published to filter.

More detailed information on query parameters is available in the Reference Guide.

Searching for APIs with categories and tags

Finding APIs by category or tag can be done using the following URL structure:

http://api.programmableweb.com/apis/-/categories_or_tags

Here is an example that shows how to retieve all APIs in category Enterprise tagged with "office"

http://api.programmableweb.com/apis/-/Enterprise/office?apikey=123

Result lists are always returned in an OpenSearch compatible Atom XML feed like the following:

<?xml version="1.0" encoding="UTF-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom">
<id>http://api.programmableweb.com/apis/-/Enterprise/office</id>
<title type="text">Programmable Web Search</title>
<subtitle type="text">Programmable Web</subtitle>
<link href="http://api.programmableweb.com/apis/-/Enterprise/office" rel="self"></link>
<logo>http://www.programmableweb.com/images/ProgrammableWebLogo.gif</logo>
<updated>2008-01-27T08:01:04Z</updated>
<entry>
        <id>http://www.programmableweb.com/api/highrise</id>
        <title type="text">Highrise</title> 

... additional entries here -- see the Reference Guide for details

</entry>
</feed>

Retrieving a specific API

To access profile details for a specific API use the API identifier returned by the search above in the <identifier> element:

http://api.programmableweb.com/apis/google-maps?apikey=123

The details of elements in an API entry can be found in our Reference Guide.

NOTE: These queries use the same API identifier used in API profiles on the main ProgrammableWeb site, all of which use the format /api/<identifier> as in http://www.programmableweb.com/api/google-maps

Retrieving mashups for an API

To access the list of mashups for a single API use the following format:

http://api.programmableweb.com/apis/google-maps/mashups?apikey=123

The results are returned as an OpenSearch compatible Atom feed. Each set of results returns up to 20 mashups. Additional mashups can be retrieved using the optional 'page=N' parameter.

Retrieving comments for an API

To access the list of comments made by users on a given API use the following format:

http://api.programmableweb.com/apis/google-maps/comments?apikey=123

As with mashups above, the results are returned as an OpenSearch compatible Atom feed, one entry per comment, and accept the same optional parameters.

Retrieving related links for an API

To access the list of an API's related links like how-to guides and tutorials use the following format:

http://api.programmableweb.com/apis/google-maps/links?apikey=123

Searching and retrieving Mashups

As with APIs, the ProgrammableWeb API provides a variety of mechanisms for finding and retrieving data about mashups. For example you can retrieve mashups by tag, name, date or developer. For a given mashup you can request a feed of that mashups users' comments.

As an example: to retrieve the list of mashups in tagged with the keyword "photo", send an HTTP GET request to the following URL

http://api.programmableweb.com/mashups/-/photo?apikey=123

The response this GET request will be an HTTP 200 status code and an OpenSearch compatible feed containing the first set of mashups tagged photo.

Each entry in the returned feed provides details on a single matching mashup from our directory

<?xml version="1.0" encoding="UTF-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom"
 xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
 xmlns:media='http://search.yahoo.com/mrss/'>
<id>http://api.programmableweb.com/mashups?apikey=123</id>
<title type="text">Programmable Web Search</title>
<subtitle type="text">Programmable Web</subtitle>
<link href="http://api.programmableweb.com/mashups?apikey=123" rel="self"></link>
<logo>http://www.programmableweb.com/images/ProgrammableWebLogo.gif</logo>
<updated>2008-02-13T10:18:43Z</updated>
<author>
	<name>ProgrammableWeb</name>
	<uri>http://www.programmableweb.com/</uri>
</author>
<generator version='beta' uri='http://api.programmableweb.com/'>ProgrammableWeb API</generator>
<openSearch:totalResults>2755</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<openSearch:itemsPerPage>20</openSearch:itemsPerPage>
<entry>
	<id>http://www.programmableweb.com/mashup/10-fascinating-googlers</id>
	<title type="text">10 Fascinating Googlers</title> 

... additional tags here -- see the Reference Guide for details

</entry>

</feed>

Retrieving a specific Mashup

To access profile details for a specific Mashup use the Mashup identifier returned by the search above in the <identifier> element:

http://api.programmableweb.com/mashups/10-fascinating-googlers?apikey=123

The details of elements in a Mashup entry can be found in our Reference Guide.

NOTE: These queries use the same Mashup identifier used in Mashup profiles on the main ProgrammableWeb site, all of which use the format /mashup/<identifier> as in http://www.programmableweb.com/mashup/10-fascinating-googlers

Retrieving comments for a Mashup

To access the list of comments made by users on a given Mashup use the following format:

http://api.programmableweb.com/mashups/10-fascinating-googlers/comments&apikey=123

The results are returned as an OpenSearch compatible Atom feed with one entry per comment. Additional comments can be retrieved using the optional 'page=N' parameter.

Sorting Results

The results are sorted alphabetically by default. Sorting by popularity, date, and rating is often useful. To sort any list, just add the sort parameter to the querystring. See the Reference Guide for explanation of sorts. For the Mashup list the valid arguments are: name, date, popular, rating, and comments. For the API list the valid arguments are: name, date, and mashups.

Full-text Search

You can do a full-text search of any list by adding the q parameter to the querystring. For example to search for election mashups:

http://api.programmableweb.com/mashups?q=election&apikey=123

Searching and retrieving Widgets

NOTE: Widget functionality on ProgrammableWeb is currently limited to API-access only. These features are not yet accessible on the public web site.

As with mashups, widgets are described by an Atom XML. Each widget is associated with a package, a version number, and an optional binary download.

As an example: to retrieve the list of widgets, send an HTTP GET request to the following URL

http://api.programmableweb.com/widgets?apikey=123

The response this GET request will be an HTTP 200 status code and an OpenSearch compatible feed containing the first set of widgets.

Each entry in the returned feed provides details on a single matching widget from our directory.

Retrieving a specific Widget

To access profile details for a specific Widget use the Widget identifier returned by the search above in the <identifier> element:

http://api.programmableweb.com/widgets/acme-accordion-1-0-0?apikey=123

The above query returns the following Atom XML feed.

<?xml version="1.0" encoding="UTF-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'>
<id>http://api.programmableweb.com/widgets?apikey=123</id>
<title type="text">Programmable Web Search</title>
<subtitle type="text">Programmable Web</subtitle>
<link href="http://api.programmableweb.com/widgets?apikey=123" rel="self"></link>
<logo>http://www.programmableweb.com/images/ProgrammableWebLogo.gif</logo>
<updated>2008-02-15T22:05:38Z</updated>
<author>
	<name>ProgrammableWeb</name>
	<uri>http://www.programmableweb.com/</uri>
</author>
<generator version='beta' uri='http://api.programmableweb.com/'>ProgrammableWeb API</generator>
<openSearch:totalResults>35</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<openSearch:itemsPerPage>20</openSearch:itemsPerPage>
<entry>
	<id>http://www.programmableweb.com/widget/acme-accordion-1-0-0</id>
	<title type="text">Accordion</title> 
	<link href="http://www.programmableweb.com/widget/acme-accordion-1-0-0"></link>
	<link rel="self" href="http://api.programmableweb.com/widgets/acme-accordion-1-0-0"></link>
	<author>
		<name>WikiAdmin</name>
	</author>
	<summary type="html">Create a accordion widget.</summary>
	<content type="application/xml">
		<acme:widget xmlns:acme="http://www.acme.com/xmlns/atom/opensearch/widgets/1.0/"> 
			<class>amce_Accordion_1_0_0</class>
			<package>acme</package>
			<version>1.0.0</version>
			<downloadUrl>
				http://www.programmableweb.com/download/acme-accordion-1-0-0
			</downloadUrl>
			<downloads>21</downloads>
			<remoteFeed></remoteFeed>
			<rating>2.5</rating>
			<name>Accordion</name>
			<label>Accordion</label>
			<author>WikiAdmin</author>
			<description>Create a accordion widget.</description>
			<type>2</type>
			<useCount>234</useCount>
			<icon>http://www.programmableweb.com/images/pw_puzzle_32x32.png</icon>
			<sampleUrl>http://sample.acme.com/widget/class/acme_Accordion_1_0_0</sampleUrl>
			<dateModified>2007-09-27T11:36:50Z</dateModified>
			<numComments>2</numComments>
			<commentsUrl>
				http://api.programmableweb.com/widgets/acme-accordion-1-0-0/comments
			</commentsUrl>
			<tags>
			</tags>
			
		</content>
	<updated>2007-09-27T11:36:50Z</updated>
</entry>
</feed>

NOTE: Because different widget platforms often use different implementation models, the content and namespace of the 'widget' element will vary by widget type. The example above uses a generic 'acme' namespace.

The details of elements in a Widget entry can be found in our Reference Guide.

NOTE: For the purposes of debugging you can view widgets on ProgrammableWeb using the same widget identifier supplied here /widget/<identifier> as in http://www.programmableweb.com/widget/acme-accordion-1-0-0

Retrieving comments for a Widget

To access the list of comments made by users on a given Widget use the following format:

http://api.programmableweb.com/widgets/acme-accordion-1-0-0/comments?apikey=123

The results are returned as an OpenSearch compatible Atom feed with one entry per comment. Additional comments can be retrieved using the optional 'page=N' parameter.

Searching and retrieving Members

Quite similar to mashups, members are described by an Atom XML. Each member can have a list of created mashups, favorite mashups, and friends. To retrieve a list of

As an example: to retrieve the list of members, send an HTTP GET request to the following URL

http://api.programmableweb.com/members?apikey=123

The response this GET request will be an HTTP 200 status code and an OpenSearch compatible feed containing the first set of members.

Each entry in the returned feed provides details on a single matching member from our directory.

Retrieving a specific Member

To access profile details for a specific Member use the Member identifier returned by the search above in the <identifier> element:

http://api.programmableweb.com/members/transpoman?apikey=123

The above query returns the following Atom XML feed.

<?xml version="1.0" encoding="UTF-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom"
 xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
 xmlns:media='http://search.yahoo.com/mrss/'>
<id>http://api.programmableweb.com/members/transpoman?apikey=123</id>
<title type="text">Programmable Web Member Data</title>
<subtitle type="text">Programmable Web Member transpoman</subtitle>
<link href="http://api.programmableweb.com/members/transpoman?apikey=123" rel="self"></link>
<logo>http://www.programmableweb.com/images/ProgrammableWebLogo.gif</logo>
<updated>2008-02-18T15:55:51Z</updated>
<author>
	<name>ProgrammableWeb</name>
	<uri>http://www.programmableweb.com/</uri>
</author>
<generator version='beta' uri='http://api.programmableweb.com/'>ProgrammableWeb API</generator>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry>
	<id>http://api.programmableweb.com/members/transpoman</id>
	<title type="text">transpoman</title>
	<link href="http://www.programmableweb.com/profile/transpoman"></link>
	<link rel="self" href="http://api.programmableweb.com/members/transpoman"></link>
	<link rel="edit" href="http://www.programmableweb.com/profile/transpoman"></link>
	<author>
		<name>transpoman</name>
	</author>
	<content type="html"></content>
		<media:title type='plain'>transpoman</media:title>
		<media:content url='http://www.programmableweb.com/images/devs/pd3.jpg'
 type='image/jpeg' medium='image' isDefault='true' />
		<media:thumbnail url='http://www.programmableweb.com/images/devs/pm3.jpg'
 height='32' width='32' />
	<updated>2008-02-18T15:33:43Z</updated>
</entry>
</feed>

The details of elements in a Member entry can be found in our Reference Guide.

NOTE: These queries use the same Member identifier used in Member profiles on the main ProgrammableWeb site, all of which use the format /profile/<identifier> as in http://www.programmableweb.com/profile/transpoman

Retrieving Member mashups

To access the list of mashups made by a specific member use the following format:

http://api.programmableweb.com/members/wuzziwug/mashups?apikey=123

The results are returned as an OpenSearch compatible Atom feed with one entry per mashup (exactly the same as the mashup list). Additional mashups can be retrieved using the optional 'page=N' parameter.

Retrieving Member favorites

To access the list of favorite mashups of a specific member use the following format:

http://api.programmableweb.com/members/jvoss/favorites?apikey=123

Retrieving Member friends

As discussed in the Reference Guide, friendships in ProgrammableWeb are one-way, so a member's friends are those who the member has chosen to show up on their profile page. To access the list of friends of a specific member use the following format:

http://api.programmableweb.com/members/transpoman/friends?apikey=123

Filtering Members

The member list has several filters that are useful for mashups. The mashups filter shows only members with mashups. The wikis filter shows only members with wikis. See the Reference Guide for full details. To use the filters, simply add the optional filter parameter to the querystring:

http://api.programmableweb.com/members?filter=mashups&apikey=123
http://api.programmableweb.com/members?filter=wikis&apikey=123

An advanced feature is filtering members by tag and api. Members who have mashups tagged or that use apis can be shown by adding the optional tags and apis parameters to the querystring:

http://api.programmableweb.com/members?tags=photo&apikey=123
http://api.programmableweb.com/members?apis=Google+Maps&apikey=123

NOTE: Unlike most api parameters, the apis parameter uses the full name of the api instead of the identifier. This is designed to make it easier to search. You still need to give the exact api name.

Adding New Entries

To add new database entries to ProgrammableWeb, you can perform an Atom APP POST to api.programmableweb.com/{type} where type is /mashups, /widgets, /feeds, or /mashups/{identifier}/comments. The details for POSTing each type are outlined below.

Adding a Mashup or Feed

NOTE: Feed functionality on ProgrammableWeb is currently limited to API-access only. These features are not yet accessible on the public web site.

You can add a mashup or feed to ProgrammableWeb by posting an Atom XML formatted request to /mashups or /feeds respectively. The formatting of this request must be followed carefully and mashup elements must use the following namespace:

<pw:mashup xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/">

The <pw:mashup> element must contain a <name> element with a proper name for the mashup. Duplicate names will not be allowed and will return an HTTP status code of 400.

A <link> element under the <entry> element with a valid url is necessary for the mashup to be useful. The first <link> tag under entry is used. Other tags in <pw:mashup> that are important are: author, description, and icon. The call will return HTTP status code "201 Created" if it is successful.

Create a mashup by POSTing to the following URL:

http://api.programmableweb.com/mashups?apikey=123

Below is an example of a valid POST to create a mashup. Highlighted fields are used by the parser. The rest are discarded.

<?xml version="1.0" encoding="UTF-8" ?>
<entry>
	<id>http://www.programmableweb.com/mashup/wii-seeker</id>
	<title type="text">Wii Seeker</title> 
	<link href="http://www.ps3seeker.com/wii/"></link>
	<author>
		<name>Unknown</name>
	</author>
	<summary type="html">A mashup to help consumers locate a Nintendo Wii. 
		Provides retail addresses, locations, dates, and local ebay auctions</summary>
		<content type="application/xml">
		<pw:mashup xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/"> 
			<rating>2.5</rating>
			<name>Wii Seeker</name>
			<label>Wii Seeker</label>
			<author>Unknown</author>
			<description>A mashup to help consumers locate a Nintendo Wii. 
			Provides retail addresses, dates, and auctions</description>
			<type></type>
			<useCount>9734</useCount>
			<icon>http://www.programmableweb.com/images/links/mt5494.jpg</icon>
			<sampleUrl>http://www.ps3seeker.com/wii/</sampleUrl>
			<dateModified>2006-12-06T08:40:19Z</dateModified>
			<numComments>0</numComments>
			<commentsUrl>
				http://api.programmableweb.com/mashups/wii-seeker/comments
			</commentsUrl>
			<tags>
				<tag>
					<name>auction</name>
					<url>http://www.programmableweb.com/tag/auction</url>
				</tag>
				<tag>
					<name>mapping</name>
					<url>http://www.programmableweb.com/tag/mapping</url>
				</tag>
				<tag>
					<name>shopping</name>
					<url>http://www.programmableweb.com/tag/shopping</url>
				</tag>
			</tags>
			<apis>
				<api>
					<name>Amazon eCommerce</name>
					<url>http://www.programmableweb.com/api/amazon-ecommerce</url>
				</api>
				<api>
					<name>eBay</name>
					<url>http://www.programmableweb.com/api/ebay</url>
				</api>
				<api>
					<name>Google Maps</name>
					<url>http://www.programmableweb.com/api/google-maps</url>
				</api>
			</apis>
		</pw:mashup>
	</content>
	<updated>2006-12-06T08:40:19Z</updated>
</entry>

Adding a Widget

You can add a widget to ProgrammableWeb by posting an Atom XML formatted request to /widgets or /feeds respectively. The formatting of this request must be followed carefully and widget elements must use the following namespace:

<acme:widget xmlns:acme="http://www.acme.com/xmlns/atom/opensearch/widgets/1.0/">

The <acme:widget> element must contain a <name> element with a proper name for the widget. Duplicate names will not be allowed and will return an HTTP status code of 400.

A <link> tag under the <entry> element with a valid url is required. Other tags in <acme:widget> that are important are: package, version, author, description, and icon. The function will return an HTTP code 201 Created if the record is created.

After adding a widget entry it is possible to upload a data file containing the widget itself. This component can later be downloaded after it has been approved by the site administrator. POST the file to http://www.programmableweb.com/download/<class> using the field name exportedzip. Note that the class name is generated by ProgrammableWeb using the package, name, and version. The download URL can be parsed from the response by the adder. It will be in the content/acme:widget/downloadUrl field. The maximum file size allowed for this upload is currently 8MB. If your widget needs more space please contact us.

The url to POST to create a widget is:

http://api.programmableweb.com/widgets?apikey=123

Below is an example of a valid post to create a widget. Highlighted fields are used by the parser. The rest are discarded.

<entry>
	<id>http://www.programmableweb.com/widget/acme-accordion-1-0-0</id>
	<title type="text">Accordion</title> 
	<link href="http://localhost/ibmmsk/acme/wiki_web_app/widget/item/class/acme_Accordion_1_0_0"></link>
	<link rel="self" href="http://api.programmableweb.com/widgets/acme-accordion-1-0-0"></link>
	<author>
		<name>WikiAdmin</name>
	</author>
	<summary type="html">Create a accordion widget.</summary>

	<content type="application/xml">
		<acme:widget xmlns:acme="http://www.acme.com/xmlns/atom/opensearch/widgets/1.0/"> 
			<class>acme_Accordion_1_0_0</class>
			<package>acme</package>
			<version>1.0.0</version>
			<downloadUrl>
					http://www.programmableweb.com/download/acme-accordion-1-0-0
			</downloadUrl>
			<downloads>21</downloads>
			<remoteFeed></remoteFeed>
			<rating>2.5</rating>
			<name>Accordion</name>
			<label>Accordion</label>
			<author>WikiAdmin</author>
			<description>Create a accordion widget.</description>
			<type>2</type>
			<useCount>236</useCount>
			<icon>http://www.programmableweb.com/images/pw_puzzle_32x32.png</icon>
			<sampleUrl>
				http://acme.com/widget/cls_Accordion_1_0_0
			</sampleUrl>
			<dateModified>2007-09-27T11:36:50Z</dateModified>
			<numComments>2</numComments>
			<commentsUrl>
				http://api.programmableweb.com/widgets/acme-accordion-1-0-0/comments
			</commentsUrl>
			<tags>
			</tags>
			
		</acme:widget>
	</content>
	<updated>2007-09-27T11:36:50Z</updated>
</entry>

Adding an API

You can add an API to ProgrammableWeb by posting an Atom XML formatted request to /apis. The formatting of this request must be followed carefully and api elements must use the following namespace:

<pw:api xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/">

The <pw:api> element must contain a <name> element with a proper name for the API. Duplicate names will not be allowed and will return an HTTP status code of 400.

A <link> tag under the <entry> element with a valid url is required. Other tags in <pw:api> that are important are: category, description, protocols, dataFormats, tags, and icon. The function will return an HTTP code 201 Created if the record is created.

The url to POST to create an API is:

http://api.programmableweb.com/apis?apikey=123

Below is an example of a valid post to create an API. Highlighted fields are used by the parser. The rest are discarded.

<entry>
	<id>http://www.programmableweb.com/api/edge-finder</id>
	<title type="text">Edge Finder</title> 
	<link href="http://www.example.com/edge-finder"></link>
	<link rel="self" href="http://api.programmableweb.com/apis/edge-finder"></link>
	<author>
		<name>Jane Developer</name>
	</author>
	<summary type="html">Image analysis</summary>
	<content type="application/xml">
		<pw:api xmlns:pw="http://www.programmableweb.com/api/opensearch/1.0/">
			<rating>3.5</rating>
			<name>Edge Finder</name>
			<label>Edge Finder</label>
			<package></package>
			<author>Jane Developer</author>
			<description>Image calculator finds all edges in a given image using the most 
efficient algorithm. Useful for machine vision.</description>
			<type>1</type>
			<downloads></downloads>
			<useCount></useCount>
			<icon>http://www.example.com/iflogo.png</icon>
			<sampleUrl></sampleUrl>
			<downloadUrl></downloadUrl>
			<dateModified>2006-02-13T09:11:52Z</dateModified>
			<remoteFeed></remoteFeed>
			<numComments></numComments>
			<commentsUrl>http://www.programmableweb.com/api/edge-finder/comments</commentsUrl>
			<tags>
				<tag>photo</tag>
			</tags>
			<category>Photos</category>
			<protocols>REST</protocols>
			<serviceEndpoint>http://api.example.com/edge-finder</serviceEndpoint>
			<version>0.1</version>
			<wsdl>    </wsdl>
			<dataFormats>XML</dataFormats>
			<apigroups>Authentication, Blogs, Contacts, Favorites, Groups, People, Photos, Tags</apigroups>
			<example>photo.Add, photo.LinkTo, 
[[http://api.example.com/docs/photoFindEdge.html photo.FindEdge]]</example>
			<clientInstall>    </clientInstall>
			<authentication>None</authentication>
			<ssl>No</ssl>
			<readonly>Yes</readonly>
			<VendorApiKits>    </VendorApiKits>
			<CommunityApiKits>    </CommunityApiKits>
			<blog>[[http://www.example.com/blog/ Blog]]</blog>
			<forum>    </forum>
			<support>    </support>
			<accountReq>    </accountReq>
			<commercial>    </commercial>
			<provider>    </provider>
			<nonCommercial>    </nonCommercial>
			<dataLicensing>    </dataLicensing>
			<fees>    </fees>
			<limits>    </limits>
			<terms>Creative Commons</terms>
			<company>    </company>
		</pw:api>
	</content>
	<updated>2006-02-13T09:11:52Z</updated>
</entry>

Modifying an API

An API may be modified after it has been created by POSTing an updated version to a proper url. The same requirements for adding an API apply to modifying an API. On success, the server will return 201 Updated and the XML data it has recorded to the database. If another person has modified the file since this data was read (thus a version conflict) you will get a 409 Conflict error. The HTTP response will contain the XML correlating to the current data. You can check this against what you expected to be there. You can then choose to resolve the conflict and then use the value of the editversion parameter in the response <link rel="edit" /> element to resubmit the entry.

Each edit URL will differ based on the optimistic concurrency value which changes the editversion parameter with each update. Thus in order to modify the API multiple times, this value will need to be set via the latest setting retrieved each time from the server.

http://api.programmableweb.com/apis/name?apikey=123&editversion=123456

The XML data to modify an API is the same as the XML data used to add an API.

Adding a Comment to a Mashup, API, Widget, or Feed

Any item on ProgrammableWeb can have a discussion thread connected to it. The API allows addition of commments using the same Atom XML that is used to display the comment. Simply POST the XML to /type/identifier/comments, the same url used to retrieve the comments.

The url to POST to create a comment on a mashup (ie. 10 Fascinating Googlers) is:

http://api.programmableweb.com/mashups/10-fascinating-googlers/comments?apikey=123

The tags that we parse are: author/name, author/email, summary, and content/comment/rating. The fields author/name and summary are required. Below is an example of a comment that can be posted.

<?xml version="1.0" encoding="UTF-8" ?>
<entry>
	<summary>This is a comment.</summary>
	<author>
		<name>WikiAdmin</name>
		<email>admin@wiki.programmableweb.com</name>
	</author>
	<content type="application/xml">
		<comment>
			<rating>5</rating>
		</comment>
	</content>
</entry>

A successful comment addition will return 201 Created and a response Atom XML that has extra items that identify the comment. We remove the author email from the xml to protect the privacy of our users.

<?xml version="1.0" encoding="UTF-8" ?>
<entry>
	<title>Accordion</title>
	<id>http://api.programmableweb.com/widgets/acme-accordion-1-0-0/comments/883</id>
	<updated>2007-09-27T11:40:14Z</updated>
	<summary>This is a comment.</summary>
	<author>
		<name>WikiAdmin</name>
	</author>
	<content type="application/xml">
		<comment>
			<username>WikiAdmin</username>
			<rating>5</rating>
		</comment>
	</content>
</entry>