Difference between revisions of "Marketplace/REST"
|Line 139:||Line 139:|
===== Compatibility Tests <br> =====
===== Compatibility Tests <br> =====
A test suite for compatibitility filtering and multiple version support is available in the Marketplace Client project. See [[Marketplace/REST/Tests]] for information on the available tests and
A test suite for compatibitility filtering and multiple version support is available in the Marketplace Client project. See [[Marketplace/REST/Tests]] for information on the available tests and them .
==== URL Variables <br> ====
==== URL Variables <br> ====
Revision as of 11:51, 9 March 2015
- 1 Eclipse Marketplace REST API Documentation
- 1.1 Provisional API
- 1.2 Retrieving a listing of all catalogs
- 1.3 Retrieving A listing of Markets and Categories
- 1.4 Retrieving a set of listings from a specific Market / Category
- 1.5 Returning a Specific Listing
- 1.6 Returning Search Results
- 1.7 Featured Listings
- 1.8 Recently Updated Listings
- 1.9 Top Favorited Listings
- 1.10 Most Popular Listings
- 1.11 Compatibility Filtering & Multiple Versions per Solution
- 1.12 URL Variables
- 2 Catalogs
- 3 Marketplace Client
Eclipse Marketplace REST API Documentation
The Eclipse Marketplace API is currently in a provisional state. The URLs for the API calls may change at any time.
This provisional API is identified by 'api/p' at the end of most URLs.
One of the goals of the API that is to make it very simple for someone to figure out how to use the API by using the website. If you add the /api/p to the websites url it should return the equivalent data in an XML response.
Retrieving a listing of all catalogs
This will return a listing of all catalogs that are browsable with the MPC. It also includes basic branding parameters, like title and icon and strategies resolving dependencies. If you want to override this url (e.g. in your RCP application) you have to set the following system-property:
This setting will request the url
http://mydomain.tld/catalogs/api/p to obtain all available catalogs.
Retrieving A listing of Markets and Categories
This will return a listing of Markets and Categories, it includes URLs for each category, as well number of listings in each category.
Retrieving a set of listings from a specific Market / Category
http://markerplace.eclipse.org/taxonomy/term/[category id],[market id]/api/p
This call returns a set of listings that correspond to the category / market specified.
Example: If you wanted to return the XML for all Build and Deploy Listings in the Tools Market you would use this call.
These urls are easily obtained from using the http://marketplace.eclipse.org/api/p call.
Returning a Specific Listing
There are two methods of returning a specific listing.
Calls to either URL will return a listing of contents of a node.
- You will need to supply the value in the URL for [title] or [node id]. These URLS will be provided in full by queries to return a subset of listings such as Categories, Searches, Featured etc.
- Most fields in the XML document are self explanitory. However there are a few fields that require explanation.
- Type - this is the type of listing being returned. 'training' is for a Training and Consulting Listing, 'resource' is for a solutions listing.
- Body - this field can and most likely contains HTML markup. This also applies to the Training and Consulting Fields (trainingdesc and consultingdesc)
- Created - this field is when the listing was first created. It is the number of seconds since the epoch. See http://us.php.net/manual/en/function.time.php for more details.
- Changed - this field is the last time this listing was changed. It is the number of seconds since the epoch. See http://us.php.net/manual/en/function.time.php for more details.
- FoundationMember - this is a boolean field. 0 meaning No, 1 meaning Yes.
- example: http://marketplace.eclipse.org/node/51/api/p will return a Training and Consulting Listing
- example: http://marketplace.eclipse.org/content/subclipse/api/p will return a Solutions Listing.
Returning Search Results
There is one exception to using the api/p at the end of URLs. The search API needs this string to be at the start of the URL.
[query] - This is the string you wish to query the database with
[page num] - The search API returns 10 results per page. Use this parameter to iterate though pages. The root node will always return the total number of results.
[filters] - There are 3 different filters used by the Apache Solr search database that can be used to constrain (Facet) your searches. If you plan to use more then one filter they must be SPACE separated.
- tid - This field is the database equivalent of category IDs.
Example : http://marketplace.eclipse.org/api/p/search/apachesolr_search/enterprise?filters=tid:9 tid:31 This query would search for 'Enterprise' in the J2EE category of the Tools Market.
- sm_field_status - this filter is the equivalent of the <status> tag in a listings XML result.
Example : http://marketplace.eclipse.org/api/p/search/apachesolr_search/enterprise?filters=sm_field_status:Production%2FStable This query would search for 'Enterprise' listings that have a Status matching 'Production/Stable'
- sm_field_licensetype - this filter is the equivalent of the <license> tag in the listings XML result.
Example : http://marketplace.eclipse.org/api/p/search/apachesolr_search/enterprise?filters=sm_field_licensetype:Free EPL' This query would search for 'Enterprise' listings that have a License Type matching "Free EPL".
This call will return a list of Featured Listings. By default this returns 6 listings. The default is configured on the server.
This call will return a list of featured listings constrained by a category / market id (or both). By default this returns 6 listings. The default is configured on the server.
- http://marketplace.eclipse.org/featured/2/api/p - This call will return featured items from the Code Management (ID = 2) Category.
- http://marketplace.eclipse.org/featured/31/api/p - This call will return featured items from the Tools (ID = 31) Market.
- http://marketplace.eclipse.org/featured/2,31/api/p - This call will return featured items that are contained in both the Code Management and Tools categories.
Recently Updated Listings
This call will return a list of Recently Updated or Added Listings. By default this returns 6 listings. The default is configured on the server.
Top Favorited Listings
This call will return a list of the Most Favorited Listings. By default this returns 6 listings. The default is configured on the server.
Most Popular Listings
This call will return a list of Most Popular listing by activity. By default this returns 6 listings. The default is configured on the server.
Compatibility Filtering & Multiple Versions per Solution
Beginning with Eclipse Mars, all listings will be subject to server-side filtering based on compatibility with the target Eclipse version. In addition, the Marketplace server supports the specification of multiple solution versions, consisting of a version number, compatibility information, an update site and installable units (features).
The Eclipse version is determined by a query parameter with key 'platform.version' that can be added to any query, e.g. http://marketplace.eclipse.org/featured/api/p?platform.version=4.4.2.v20150204-1700. Its value should correspond to the version of the org.eclipse.platform bundle of the target Eclipse. Older MPC versions instead use the parameter 'runtime.version' with the version of the org.eclipse.core.runtime bundle. The server will use this as a fall-back if 'platform.version' is not available.
If no version information is available, the unfiltered results are returned. Otherwise, incompatible solutions will not be included in any listing. Requests to specific nodes will still return the node information, but not include any installable units or an update site url. Node detail information of compatible solutions will include the installable units, update site and version information for the pertinent Eclipse version. If multiple solution version specifications match the target Eclipse version, the last one in the list with support for the newest Eclipse version will be used.
A test suite for compatibitility filtering and multiple version support is available in the Marketplace Client project. See Marketplace/REST/Tests for information on the available tests and how to run them yourself.
[client] - The only valid value for the client variable is "org.eclipse.epp.mpc.core". This variable is usually sent from MPC to alter the default list. It's available for the Most Popular Listings, Top Favorited Listings, Recently Updated Listings and Featured Listings. Only installable listings owned by an Eclipse member company will be returned.
Featured Listings : If available, it can insert up-to two promoted downloads at the top of the list. It is possible to see a commercial listing here.
Recently Updated Listings, Top Favorited Listings & Most Popular Listings: Only returns listings that don't have a commercial license.
What is a Catalog
A catalog is an HTTP service which returns XML data back to the Marketplace Client from. Currently Marketplace uses PHP with an SQL backend to serve these pages to the MPC.
Building a Catalog
In terms of building your own catalog with this data you would follow a three step process.
- Query the Base URL for a listing of Markets and their categories.
- Iterate through that query to retrieve listings for each category using the Category URL.
- Finally iterate through the Category Query to retrieve the data related to each node.
For MPC Kepler, it's going to be possible to add an additional tab containing an embedded browser component that shows a news page. The page URL to display will be included in the marketplace catalog description pulled from the server. It's possible to override a catalog default URL with news/api/p.
Here's an example of the default Eclipse Marketplace catalog news page: http://marketplace.eclipse.org/news/api/p
The Marketplace Client (MPC) project implements a client to the REST API. Though the client does not provide public Java API for accessing the REST API, it may be useful for testing purposes when building a catalog.
Of interest to catalog providers or implementors of client libraries to access the REST API in MPC:
- /org.eclipse.epp.mpc.core/mpc-rest.xsd An XML Schema that describes the REST API data format
org.eclipse.epp.internal.mpc.core.service.DefaultMarketplaceServiceA Java class that provides a Java API to the REST service
org.eclipse.epp.mpc.tests.service.DefaultMarketplaceServiceTestA JUnit test case that exercises the REST API