REST API - Revision history

Scott at 20:16, 3 July 2014

2014-07-03T20:16:40Z

Scott at 13:03, 21 February 2014

2014-02-21T13:03:50Z

Scott at 11:59, 21 February 2014

2014-02-21T11:59:18Z

Scott at 11:58, 21 February 2014

2014-02-21T11:58:20Z

Scott at 11:57, 21 February 2014

2014-02-21T11:57:50Z

Scott at 11:51, 21 February 2014

2014-02-21T11:51:57Z

Scott at 11:42, 21 February 2014

2014-02-21T11:42:35Z

Scott at 11:42, 21 February 2014

2014-02-21T11:42:01Z

Scott at 11:40, 21 February 2014

2014-02-21T11:40:15Z

Scott at 05:53, 21 February 2014

2014-02-21T05:53:13Z

← Older revision		Revision as of 20:16, 3 July 2014
Line 155:		Line 155:

	Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).		Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).
		+
		+	Also note that once you have specified one or more ''type''Weights, only those types which have been assigned a weight will be included in the computations.

	==== Additional query options ====		==== Additional query options ====

← Older revision		Revision as of 13:03, 21 February 2014
Line 148:		Line 148:
	This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.		This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.

		+	==== ''type''Weight ====
		+
		+	If you've used different [[XML Format#type attribute\|link types]] in your data, you can specify different link weights for the different link types in the query. For example, if you used the type ''viewed'' and ''linked'' you could do:
		+
		+	<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?\|viewedWeight=5&linkedWeight=10}}</tt>
		+
		+	Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).

	==== Additional query options ====		==== Additional query options ====

@@ Line 52: / Line 52: @@
 <tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt>
 <tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt>
 == Item resource ==

@@ Line 68: / Line 68: @@
 Updates or creates an item overwriting all of its current contents.  The item identifier used in the XML must match the resource name that you're updating or creating.  This may contain tags, properties and links and will overwrite all of the current data associated with this item.  Items that ''link'' to this item will not be affected.
 === HTTP POST ===
@@ Line 86: / Line 82: @@
 <tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt>
 <tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt>
 == Related / recommended resources ==

← Older revision		Revision as of 11:57, 21 February 2014
Line 72:		Line 72:

	Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.		Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.
		+
		+	=== HTTP POST ===
		+
		+	This is used for updating items (potentially incrementally). The key [[Recommendation parameters\|query parameter]] is '''updateMethod'''. Valid values are:
		+
		+	* '''replace''': This is the default. This means that the posted content should replace the item.
		+	* '''add''': This means that the posted content should be added to the already existing content.
		+	* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.
		+
		+	These would be, respectively:
		+
		+	<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?\|updateMethod=replace}}</tt>
		+	<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?\|updateMethod=add}}</tt>
		+	<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?\|updateMethod=subtract}}</tt>

	== Related / recommended resources ==		== Related / recommended resources ==

@@ Line 46: / Line 46: @@
 * '''add''': This means that the posted content should be added to the already existing content in the database.
 * '''subtract''': This means that the values should be ''subtracted'' from the database.  In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.  If an item does not contain any additional tags in this data, then the item itself will be removed.
 == Item resource ==

← Older revision		Revision as of 11:42, 21 February 2014
Line 66:		Line 66:

	Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.		Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.
−
−	~~=== Add and remove sub-resources ===~~
−
−	~~: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''~~
−
−	~~<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/\|add}}</tt>~~
−	~~<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/\|remove}}</tt>~~
−
−	Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.
−
−	The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.
−
−	~~The typical use cases are adding a tag to a given item, or removing a property.~~
−
−	~~The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.~~
−
−	~~==== HTTP PUT ====~~
−
−	~~In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.~~
−
−	Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.

	== Related / recommended resources ==		== Related / recommended resources ==

← Older revision		Revision as of 11:42, 21 February 2014
Line 38:		Line 38:

	Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.		Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.
−

	=== HTTP POST ===		=== HTTP POST ===

← Older revision		Revision as of 11:40, 21 February 2014
Line 38:		Line 38:

	Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.		Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.
		+
		+
		+	=== HTTP POST ===
		+
		+	This is used for updating the database in batch. The key [[Recommendation parameters\|query parameter]] is '''updateMethod'''. Valid values are:
		+
		+	* '''replace''': This is the default. This means that the posted content should replace everything in the database.
		+	* '''add''': This means that the posted content should be added to the already existing content in the database.
		+	* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.

	== Item resource ==		== Item resource ==

← Older revision		Revision as of 05:53, 21 February 2014
Line 30:		Line 30:

	Also note that your database name is the same as your user name.		Also note that your database name is the same as your user name.
−
−	~~=== Add sub-resource ===~~
−
−	You can incrementally do batch updates to the database by appending ''add'' to the end of the URL. The XML format is the same as for a normal import, but it will not first clear the database the items in the database will be the combination of previously existing data, plus the new data. Specifically, if you already had an item with some links and tags and wanted to add another tag, you would enter that item with no data other than the new tag and the result would be an item with those properties and links, plus the new tag.
−
−	~~<tt>{{URL\|username:password@webservices.directededge.com/api/v1/wikipedia/\|add\|}}</tt>~~
−

	=== HTTP GET ===		=== HTTP GET ===