Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Marketplace/REST"

(URL Variables)
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Eclipse Marketplace REST API Documentation ==
+
= Eclipse Marketplace REST API Documentation =
  
==== Provisional API<br>  ====
+
== General Usage ==
  
The Eclipse Marketplace API is currently in a provisional state. The URLs for the API calls may change at any time.
+
This API is identified by 'api/p' at the end of most URLs.<br>
 
+
This provisional API is identified by 'api/p' at the end of most URLs.<br>  
+
  
 
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.
 
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.
  
<br>  
+
We only returns listings that don't have a commercial license for the Recently Updated Listings, Top Favorited Listings & Most Popular Listings''' API calls.
 +
 
 +
=== URL Variables ===
 +
 
 +
*<code> client: [string]</code> The only valid value for the client variable is <code>org.eclipse.epp.mpc.core</code>. 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.
 +
* <code>product: [string]</code> The product id of the target Eclipse, e.g. <code>org.eclipse.sdk.ide</code> or <code>epp.package.java</code>
 +
* <code>product.version: [osgi version]</code> The version of the running product of the target Eclipse, identical to the version of the product's branding plugin
 +
* <code>runtime.version: [osgi version]</code> The version of the org.eclipse.core.runtime bundle of the target Eclipse
 +
* <code>platform.version: [osgi version]</code> ''(since Kepler/MPC 1.2)'' The version of the org.eclipse.platform bundle of the target Eclipse
 +
* <code>java.version: [string]</code> The version of the JRE running the target Eclipse, as returned by the JRE's <code>System.getProperty("java.version")</code>
 +
* <code>os: [string]</code> Operating system of the user. Supported values are <code>linux</code>, <code>win32</code> and <code>macosx</code>.
 +
* <code>ws: [string]</code> Window system of the user. Supported values are <code>gtk</code>, <code>win32</code> and <code>cocoa</code>.
 +
* <code>nl: [string]</code> Language code of the user's locale, e.g. <code>en_US</code> or <code>de_DE</code>.
 +
 
 +
Example: http://marketplace.eclipse.org/featured/api/p?client=org.eclipse.epp.mpc.core&product=epp.package.java&product.version=1.5.1.20121004-1506&runtime.version=3.8.0.v20120521-2346&platform.version=4.2.1.v201209141800&java.version=1.7.0_55&os=win32&ws=win32&nl=de_DE
 +
 
 +
 
 +
== 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. See [[#Determining the Eclipse release version]] for details.
 +
 
 +
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.
 +
 
 +
=== Compatibility Tests ===
 +
 
 +
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.
 +
 
 +
=== Determining the Eclipse release version ===
 +
 
 +
The Eclipse release version used to filter entries based on their stated compatibility is determined based on the query parameters sent with the request, see [[#URL Variables]]. The release version is calculated as follows:
 +
 
 +
# If <code>platform.version</code> exists, use it as the release version - This is the case for all versions of MPC since Kepler/MPC 1.2.0.
 +
# If <code>product</code> is one of <code>org.eclipse.sdk.ide</code> or <code>org.eclipse.platform.ide</code>, use <code>product.version</code> as the release version. For these two product ids, the product.version is known to match the Eclipse release version (in general, that's not the case). This covers Eclipse 3.8 releases. For Juno, there were two parallel releases, 3.8 and 4.2. Those releases cannot be distinguished by their runtime.version, and platform.version isn't sent by those releases. However, the only official Eclipse.org releases for 3.8 were the two products listed here. For other product ids, the product.version is arbitrary and cannot be used to infer the Eclipse release version.
 +
# Use <code>runtime.version</code> - Older release versions correspond to the major/minor version of the runtime plugin. Since the move to 4.x, this is no longer te case (i.e. Juno still had a runtime.version of 3.8.x and Kepler had a runtime.version of 3.9.x)
 +
 
 +
With the calculated release version, the release can be determined from the following mapping:
 +
* '''4.5.x.xxx''' (Mars)
 +
* '''4.4.x.xxx''' (Luna)
 +
* '''4.3.x.xxx''' (Kepler)
 +
* '''4.2.x.xxx''' (Juno)
 +
* '''3.8.x.xxx''' (Eclipse 3.8 - parallel release to Juno)
 +
* '''3.7.x.xxx''' (Indigo)
 +
* '''3.6.x.xxx''' (Helios)
 +
* ...
 +
 
 +
If the calculated release version cannot be matched to an Eclipse release, no filtering will be performed.
  
==== Retrieving a listing of all catalogs ====
+
== Retrieving a listing of all catalogs ==
  
 
http://marketplace.eclipse.org/catalogs/api/p
 
http://marketplace.eclipse.org/catalogs/api/p
Line 22: Line 67:
  
  
==== Retrieving A listing of Markets and Categories<br>  ====
+
''' XML example '''
  
http://marketplace.eclipse.org/api/p
+
  <marketplace>
 +
    <catalogs>
 +
      <catalog id="38413" title="Eclipse Marketplace" url="http://mydomain.tld" selfContained="0" icon="http://marketplace.eclipse.org/sites/default/files/default_1_0.png">
 +
        <description>Eclipse Marketplace (MP) is a place to find and keep track of Eclipse-based solutions.</description>
 +
        <dependenciesRepository></dependenciesRepository>
 +
        <wizard title="">
 +
          <icon>http://marketplace.eclipse.org/sites/default/files/default_1.png</icon>
 +
          <searchtab enabled="1">Search</searchtab>
 +
          <populartab enabled="1">Popular</populartab>
 +
          <recenttab enabled="1">Recent</recenttab>
 +
          <news shorttitle="January 01/27" timestamp="1422334800">https://www.eclipse.org/community/eclipse_newsletter/2015/january/</news>
 +
      </wizard>
 +
    </catalog>
 +
  </marketplace>
  
This will return a listing of Markets and Categories, it includes URLs for each category, as well number of listings in each category.  
+
*marketplace
 +
**catalogs
 +
***catalog
 +
****(@attribute) '''id''': [int] Unique identifier
 +
****(@attribute) '''title''': [string] Name of catalog
 +
****(@attribute) '''url''': [string] Url prefix of the marketplace catalog
 +
****(@attribute) '''selfContained''': [bool] TRUE/FALSE
 +
****(@attribute) '''icon''': [string] Absolute url
 +
****'''description''': [string] Short description
 +
****'''dependenciesRepository''': [string]
 +
****wizard
 +
*****(@attribute) '''title''': [string] Title of Wizard
 +
*****'''icon''': [string] Absolute url
 +
*****'''searchtab''': [string] Search tab title
 +
******(@attribute) '''enabled''': [bool] TRUE/FALSE
 +
*****'''populartab''': [string] Popular tab title
 +
******(@attribute) '''enabled''': [bool] TRUE/FALSE
 +
*****'''recenttab''': [string] Recent tab title
 +
******(@attribute) '''enabled''': [bool] TRUE/FALSE
 +
*****'''news''': [string] News content URL.
 +
******(@attribute) '''enabled''': [bool] TRUE/FALSE
  
 +
== Retrieving A listing of Markets and Categories ==
  
 +
http://marketplace.eclipse.org/api/p
  
==== Retrieving a set of listings from a specific Market / Category <br>  ====
+
This will return a listing of Markets and Categories, it includes URLs for each category, as well number of listings in each category.
 +
 
 +
 
 +
''' XML example '''
 +
 
 +
  <marketplace>
 +
    <market name="Tools" id="31" url="http://marketplace.eclipse.org/category/markets/tools">
 +
      <category id="1964" count="158" url="http://marketplace.eclipse.org/taxonomy/term/1964%2C31" name="Application Development Frameworks" />
 +
    </market>
 +
    <market name="Long Term Support" id="3429" url="http://marketplace.eclipse.org/category/markets/long-term-support" />
 +
  </marketplace>
 +
 
 +
*marketplace
 +
**market
 +
***(@attribute) '''name''': [string] Title
 +
***(@attribute) '''id''': [int] Unique identifier
 +
***(@attribute) '''url''': [string] Url
 +
***category (optional)
 +
****(@attribute) '''id''': [int] Unique identifier
 +
****(@attribute) '''count''': [int] Listing count
 +
****(@attribute) '''url''': [string] Url
 +
****(@attribute) '''name''': [string] Title
 +
 
 +
== Retrieving a set of listings from a specific Market / Category ==
  
 
<nowiki>http://markerplace.eclipse.org/taxonomy/term/[category id],[market id]/api/p</nowiki>
 
<nowiki>http://markerplace.eclipse.org/taxonomy/term/[category id],[market id]/api/p</nowiki>
  
This call returns a set of listings that correspond to the category / market specified.  
+
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.  
+
Example: If you wanted to return the XML for all Build and Deploy Listings in the Tools Market you would use this call.
  
http://marketplace.eclipse.org/taxonomy/term/4,31/api/p  
+
http://marketplace.eclipse.org/taxonomy/term/4,31/api/p
  
 
These urls are easily obtained from using the http://marketplace.eclipse.org/api/p call.
 
These urls are easily obtained from using the http://marketplace.eclipse.org/api/p call.
  
==== Returning a Specific Listing<br>  ====
 
  
There are two methods of returning a specific listing.  
+
''' XML example '''
 +
 
 +
  <marketplace>
 +
    <category id="4" marketid="31" name="Build and Deploy" url="http://marketplace.eclipse.org/taxonomy/term/4%2C31">
 +
      <node id="69" name="MyEclipse Enterprise Workbench" url="http://marketplace.eclipse.org/content/myeclipse-enterprise-workbench">
 +
        <favorited>34</favorited>
 +
        <installstotal>5394</installstotal>
 +
        <installsrecent>0</installsrecent>
 +
      </node>
 +
    </category>
 +
  </marketplace>
 +
 
 +
*marketplace
 +
**category
 +
***(@attribute) '''id''': [int] Unique identifier
 +
***(@attribute) '''marketid''': [int] Unique identifier
 +
***(@attribute) '''name''': [string] Title
 +
***(@attribute) '''url''': [string] Url
 +
***node
 +
****(@attribute) '''id''': [int] Unique identifier
 +
****(@attribute) '''name''': [string] Listing Title
 +
****(@attribute) '''url''': [string] Listing Url
 +
****'''favorited''': [int] Number of times a listing was favorited
 +
****'''installstotal''': [int] Install count
 +
****'''installsrecent''': [int] Install count for the last month
 +
 
 +
== Returning a Specific Listing  ==
 +
 
 +
There are two methods of returning a specific listing.
  
 
<nowiki>http://marketplace.eclipse.org/content/[title]/api/p </nowiki>
 
<nowiki>http://marketplace.eclipse.org/content/[title]/api/p </nowiki>
  
and  
+
and
  
 
<nowiki>http://marketplace.eclipse.org/node/[node id]/api/p </nowiki>
 
<nowiki>http://marketplace.eclipse.org/node/[node id]/api/p </nowiki>
  
Calls to either URL will return a listing of contents of a node.<br>  
+
Calls to either URL will return a listing of contents of a node.<br>
  
*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.<br>
 
*Type - this is the type of listing being returned. 'training' is for a Training and Consulting Listing, 'resource' is for a solutions listing.<br>
 
*Body - this field can and most likely contains HTML markup. This also applies to the Training and Consulting Fields (trainingdesc and consultingdesc)<br>
 
*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.<br>
 
*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.<br>
 
*FoundationMember - this is a boolean field. 0 meaning No, 1 meaning Yes.<br>
 
*example: http://marketplace.eclipse.org/node/51/api/p will return a Training and Consulting Listing<br>
 
*example: http://marketplace.eclipse.org/content/subclipse/api/p will return a Solutions Listing. <br>
 
  
==== Returning Search Results <br>  ====
+
''' XML example '''
  
<nowiki>http://marketplace.eclipse.org/api/p/search/apachesolr_search/[query]?page=[page num]&amp;filters=[filters] </nowiki>
+
  <marketplace>
 +
    <node id="29591" name="JRebel for Eclipse" url="http://mydomain.tld/content/example">
 +
      <type>resource</type>
 +
      <categories>
 +
        <category id="4" name="Build and Deploy" url="http://mydomain.tld/category/categories/build-and-deploy" />
 +
        <category id="24" name="IDE" url="http://mydomain.tld/category/categories/ide" />
 +
        <category id="9" name="J2EE Development Platform" url="http://mydomain.tld/category/categories/j2ee-development-platform" />
 +
        <category id="17" name="Tools" url="http://mydomain.tld/category/categories/tools" />
 +
        <category id="20" name="Web" url="http://mydomain.tld/category/categories/web" />
 +
      </categories>
 +
      <tags>
 +
        <tag id="134" name="J2EE" url="http://mydomain.tld/category/free-tagging/j2ee" />
 +
        <tag id="327" name="eclipse" url="http://mydomain.tld/category/free-tagging/eclipse" />
 +
        <tag id="422" name="java ee" url="http://mydomain.tld/category/free-tagging/java-ee" />
 +
        <tag id="573" name="tools" url="http://mydomain.tld/category/free-tagging/tools" />
 +
        <tag id="614" name="productivity" url="http://mydomain.tld/category/free-tagging/productivity" />
 +
      </tags>
 +
      <owner>Oliver White</owner>
 +
      <favorited>66</favorited>
 +
      <installstotal>0</installstotal>
 +
      <installsrecent>140372</installsrecent>
 +
      <shortdescription>SHORT DESCRIPTION</shortdescription>
 +
      <body>LONG DESCRIPTION</body>
 +
      <created>1295963961</created>
 +
      <changed>1424896414</changed>
 +
      <foundationmember>1</foundationmember>
 +
      <homepageurl>http://www.zeroturnaround.com/software/jrebel/</homepageurl>
 +
      <image>http://mydomain.tld/sites/all/themes/solstice/_themes/solstice_marketplace/public/images/default.png</image>
 +
      <license>Commercial</license>
 +
      <companyname>ZeroTurnaround</companyname>
 +
      <status>Mature</status>
 +
      <supporturl>http://www.zeroturnaround.com/jrebel/documentation/</supporturl>
 +
      <version />
 +
      <eclipseversion>4.5, 4.4, 4.3, 4.2, 4.1</eclipseversion>
 +
      <updateurl>http://update.zeroturnaround.com/update-site</updateurl>
 +
      <ius>
 +
        <iu selected="TRUE">org.zeroturnaround.eclipse.feature</iu>
 +
        <iu selected="TRUE">org.zeroturnaround.eclipse.wtp.feature</iu>
 +
        <iu selected="TRUE">org.zeroturnaround.eclipse.m2e.feature</iu>
 +
      </ius>
 +
      <platforms>
 +
        <platform>Windows</platform>
 +
        <platform>Mac</platform>
 +
        <platform>Linux/GTK</platform>
 +
      </platforms>
 +
    </node>
 +
  </marketplace>
 +
 
 +
*marketplace
 +
**node
 +
***(@attribute) '''id''': [int] Unique identifier
 +
***(@attribute) '''name''': [string] Listing Title
 +
***(@attribute) '''url''': [string] Listing Url
 +
***'''type''': [string] This is the type of listing being returned. 'training' is for a Training and Consulting Listing, 'resource' is for a solutions listing.
 +
***categories
 +
****(@attribute) '''id''': [int] Unique identifier
 +
****(@attribute) '''name''': [string] Title
 +
****(@attribute) '''url''': [string] Url
 +
***'''owner''': [string] Name of the author
 +
***'''favorited''': [int] Number of times a listing was favorited
 +
***'''installstotal''': [int] Install count
 +
***'''installsrecent''': [int] Install count for the last month
 +
***'''shortdescription''': [string] Listing teaser
 +
***'''body''': [sting] Full description
 +
***'''created''': [int] Timestamp
 +
***'''changed''': [int] Timestamp
 +
***'''foundationmember''': [bool] TRUE/FALSE
 +
***'''homepageurl''': [string] Listing URL website
 +
***'''image''': [string] Logo absolute URL
 +
***'''license''': [string] Listing license
 +
***'''companyname''': [string] Company name
 +
***'''status''': [string] Release status
 +
***'''supporturl''': [string] Support/documentation URL
 +
***'''version''': [string] Version name
 +
***'''eclipseversion''': [float] Eclipse release number (4.5, 4.4...)
 +
***'''updateurl''': [string] Update site URL
 +
***'''ius: Feature ID's are used by the Eclipse Marketplace Client (MPC) to determine which features to install for your listing https://marketplace-staging.eclipse.org/feature-how-to
 +
****iu
 +
*****(@attribute) '''required''': [string] TRUE or FALSE
 +
*****(@attribute) '''selected''': [string] TRUE or FALSE
 +
****platforms
 +
*****'''platform''': [string] Compatible OS (Windows, Mac, Linux/GTK)
  
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.
+
=== Examples ===
  
===== URL Variables <br> =====
+
*example: http://marketplace.eclipse.org/node/51/api/p will return a Training and Consulting Listing<br>
 +
*example: http://marketplace.eclipse.org/content/subclipse/api/p will return a Solutions Listing. <br>
  
[query] - This is the string you wish to query the database with
+
== Returning Search Results ==
  
[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.
+
<nowiki>http://marketplace.eclipse.org/api/p/search/apachesolr_search/[query]?page_num=[page num]&amp;filters=[filters] </nowiki>
  
[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.  
+
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.
  
*tid - This field is the database equivalent of category IDs.
+
=== URL Variables ===
  
Example&nbsp;: 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.  
+
*'''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 &lt;status&gt; 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 &lt;license&gt; 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".
  
*sm_field_status - this filter is the equivalent of the &lt;status&gt; tag in a listings XML result.
 
  
Example&nbsp;: http://marketplace.eclipse.org/api/p/search/apachesolr_search/enterprise?filters=ss_cck_field_status:Production%2FStable This query would search for 'Enterprise' listings that have a Status matching 'Production/Stable'  
+
''' XML example '''
  
*sm_field_licensetype - this filter is the equivalent of the &lt;license&gt; tag in the listings XML result.
+
  <marketplace>
 +
    <search term="test" url="http://marketplace-staging.eclipse.org/search/content/test" count="1">
 +
      <node>[[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]</node>
 +
    </search>
 +
  </marketplace>
  
Example&nbsp;: http://marketplace.eclipse.org/api/p/search/apachesolr_search/enterprise?filters=ss_cck_field_licensetype:'Free EPL' This query would search for 'Enterprise' listings that have a License Type matching "Free EPL".
+
*marketplace
 +
**search
 +
***(@attribute) '''term''': [string] Search keyword
 +
***(@attribute) '''url''': [string] Url
 +
***(@attribute) '''count''': [int] Result count
 +
***node: [[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]
  
==== Featured Listings ====
+
== Featured Listings ==
  
http://marketplace.eclipse.org/featured/api/p  
+
http://marketplace.eclipse.org/featured/api/p
  
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. By default this returns 6 listings. The default is configured on the server.
  
<br> http://marketplace.eclipse.org/featured/%/api/p
+
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.
  
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.  
+
<br> http://marketplace.eclipse.org/featured/%/api/p
  
Example:
+
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.  
+
Example:
*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/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.
 
*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.
  
<br/>
+
''' XML example '''
  
==== Recently Updated Listings ====
+
  <marketplace>
 +
    <featured count="10">
 +
      <node>[[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]</node>
 +
    </featured>
 +
  </marketplace>
 +
 
 +
*marketplace
 +
**featured
 +
***(@attribute) '''count''': [int] Result count
 +
***node: [[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]
 +
 
 +
== Recently Updated Listings ==
  
 
http://marketplace.eclipse.org/recent/api/p
 
http://marketplace.eclipse.org/recent/api/p
Line 114: Line 346:
 
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.
 
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.
  
 +
''' XML example '''
 +
 +
  <marketplace>
 +
    <recent count="10">
 +
      <node>[[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]</node>
 +
    </recent>
 +
  </marketplace>
 +
 +
*marketplace
 +
**recent
 +
***(@attribute) '''count''': [int] Result count
 +
***node: [[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]
  
==== Top Favorited Listings ====
+
== Top Favorited Listings ==
  
 
http://marketplace.eclipse.org/favorites/top/api/p
 
http://marketplace.eclipse.org/favorites/top/api/p
Line 121: Line 365:
 
This call will return a list of the Most Favorited Listings.  By default this returns 6 listings.  The default is configured on the server.
 
This call will return a list of the Most Favorited Listings.  By default this returns 6 listings.  The default is configured on the server.
  
 +
''' XML example '''
  
==== Most Popular Listings ====
+
  <marketplace>
 +
    <favorites count="10">
 +
      <node>[[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]</node>
 +
    </favorites>
 +
  </marketplace>
 +
 
 +
*marketplace
 +
**favorites
 +
***(@attribute) '''count''': [int] Result count
 +
***node: [[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]
 +
 
 +
== Most Popular Listings ==
  
 
http://marketplace.eclipse.org/popular/top/api/p
 
http://marketplace.eclipse.org/popular/top/api/p
Line 128: Line 384:
 
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.
 
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.
  
 +
''' XML example '''
 +
 +
  <marketplace>
 +
    <popular count="10">
 +
      <node>[[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]</node>
 +
    </recent>
 +
  </marketplace>
 +
 +
*marketplace
 +
**popular
 +
***(@attribute) '''count''': [int] Result count
 +
***node: [[Marketplace/REST#Returning_a_Specific_Listing|Please refer to Returning a Specific Listing section.]]
 +
 +
== Related Entries ==
 +
 +
http://marketplace.eclipse.org/related/api/p
  
==== URL Variables <br> ====
+
This call will return a list of entries related to what's already installed in the running Eclipse. Installed entries are sent to the server as node ids in an additional query parameter
  
[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.  
+
<code>nodes</code>: A list of space-separated node ids for installed marketplace nodes, url-encoded.
  
'''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.
+
Example:
  
'''Recently Updated Listings, Top Favorited Listings & Most Popular Listings''': Only returns listings that don't have a commercial license.
+
http://marketplace.eclipse.org/related/api/p?nodes=12345+23456+34567
  
Example: http://marketplace.eclipse.org/featured/api/p?client=org.eclipse.epp.mpc.core
+
This feature is already supported by the MPC client through a 'Related' tab that needs to be enabled in the catalog's branding information, see [[Marketplace/REST#Catalog_Description|Catalog Description]]. The server at marketplace.eclipse.org does not yet support this query at the moment, see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=453244 bug 453244].
  
 
= Catalogs =
 
= Catalogs =
Line 151: Line 423:
 
#Iterate through that query to retrieve listings for each category using the Category URL.
 
#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.
 
#Finally iterate through the Category Query to retrieve the data related to each node.
 +
 +
=== Catalog Description ===
 +
 +
Catalogs are managed through a registry on marketplace.eclipse.org. Each catalog is listed with its REST URL and branding information (Title, catalog icon, MPC wizard icon, supported MPC tabs).
 +
 +
A list of catalogs can be retrieved from http://marketplace.eclipse.org/catalogs/api/p
 +
 +
''' XML Example '''
 +
 +
  <marketplace>
 +
    <catalogs>
 +
      <catalog id="38413" title="Eclipse Marketplace" url="http://marketplace.eclipse.org" selfContained="0"
 +
                icon="http://marketplace.eclipse.org/sites/default/files/marketplace_catalog_icon-32.png">
 +
        <description>
 +
          Eclipse Marketplace (MP) is a place to find and keep track of Eclipse-based solutions.
 +
        </description>
 +
        <dependenciesRepository/>
 +
        <wizard title="">
 +
          <icon>http://marketplace.eclipse.org/sites/default/files/marketplace_catalog_icon_0.png</icon>
 +
          <searchtab enabled="1">Search</searchtab>
 +
          <featuredmarkettab enabled="1">Eclipse Project</featuredmarkettab>
 +
          <populartab enabled="1">Popular</populartab>
 +
          <recenttab enabled="1">Recent</recenttab>
 +
          <relatedtab enabled="1">Related</relatedtab>
 +
          <news shorttitle="March 05/26" timestamp="1432612800">https://www.eclipse.org/community/eclipse_newsletter/2015/may</news>
 +
        </wizard>
 +
      </catalog>
 +
    </catalogs>
 +
  </marketplace>
 +
 +
=== News Page ===
 +
 +
Since MPC Kepler, it's 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
  
 
= Marketplace Client =
 
= Marketplace Client =
  
The [http://www.eclipse.org/mpc 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.
+
The [http://www.eclipse.org/mpc Marketplace Client] (MPC) project implements a client to the REST API.  The client provides public Java API for accessing the REST API in the org.eclipse.epp.mpc.core plug-in through the classes in the org.eclipse.epp.mpc.core.service package.
 +
 
 +
Of interest to clients to the REST API:
 +
* <code>IMarketplaceServiceLocator</code> is an OSGi service that can be used as an entry point to access the catalog service and specific marketplace services.
 +
* <code>IMarketplaceService</code> gives access to the marketplace REST API
 +
* <code>ICatalogService</code> gives access to the catalog registry
 +
* The marketplace data model is available through interfaces in the <code>org.eclipse.epp.mpc.model</code> package.
 +
 
 +
In addition to the Java REST API, there is also some API to access the Marketplace Client wizard dialog in the org.eclipse.epp.mpc.ui plug-in:
 +
* <code>MarketplaceClient</code> offers some simple helper methods to open a wizard and to give access to the more elaborate IMarketplaceClientService
 +
* <code>IMarketplaceClientService</code> offers more elaborate configuration options to open a wizard in a specific state, e.g. with specific markets, entries preselected for install, or directly on the installation page.
  
Of interest to catalog providers or implementors of client libraries to access the REST API in MPC:
+
Furthermore, of interest to catalog providers or implementors of client libraries to access the REST API in MPC:
 
* <tt>/org.eclipse.epp.mpc.core/mpc-rest.xsd</tt> An XML Schema that describes the REST API data format
 
* <tt>/org.eclipse.epp.mpc.core/mpc-rest.xsd</tt> An XML Schema that describes the REST API data format
 
* <code>org.eclipse.epp.internal.mpc.core.service.DefaultMarketplaceService</code> A Java class that provides a Java API to the REST service
 
* <code>org.eclipse.epp.internal.mpc.core.service.DefaultMarketplaceService</code> A Java class that provides a Java API to the REST service
 
* <code>org.eclipse.epp.mpc.tests.service.DefaultMarketplaceServiceTest</code> A JUnit test case that exercises the REST API
 
* <code>org.eclipse.epp.mpc.tests.service.DefaultMarketplaceServiceTest</code> A JUnit test case that exercises the REST API

Revision as of 08:23, 29 May 2015

Eclipse Marketplace REST API Documentation

General Usage

This 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.

We only returns listings that don't have a commercial license for the Recently Updated Listings, Top Favorited Listings & Most Popular Listings API calls.

URL Variables

  • client: [string] 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.
  • product: [string] The product id of the target Eclipse, e.g. org.eclipse.sdk.ide or epp.package.java
  • product.version: [osgi version] The version of the running product of the target Eclipse, identical to the version of the product's branding plugin
  • runtime.version: [osgi version] The version of the org.eclipse.core.runtime bundle of the target Eclipse
  • platform.version: [osgi version] (since Kepler/MPC 1.2) The version of the org.eclipse.platform bundle of the target Eclipse
  • java.version: [string] The version of the JRE running the target Eclipse, as returned by the JRE's System.getProperty("java.version")
  • os: [string] Operating system of the user. Supported values are linux, win32 and macosx.
  • ws: [string] Window system of the user. Supported values are gtk, win32 and cocoa.
  • nl: [string] Language code of the user's locale, e.g. en_US or de_DE.

Example: http://marketplace.eclipse.org/featured/api/p?client=org.eclipse.epp.mpc.core&product=epp.package.java&product.version=1.5.1.20121004-1506&runtime.version=3.8.0.v20120521-2346&platform.version=4.2.1.v201209141800&java.version=1.7.0_55&os=win32&ws=win32&nl=de_DE


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. See #Determining the Eclipse release version for details.

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.

Compatibility Tests

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.

Determining the Eclipse release version

The Eclipse release version used to filter entries based on their stated compatibility is determined based on the query parameters sent with the request, see #URL Variables. The release version is calculated as follows:

  1. If platform.version exists, use it as the release version - This is the case for all versions of MPC since Kepler/MPC 1.2.0.
  2. If product is one of org.eclipse.sdk.ide or org.eclipse.platform.ide, use product.version as the release version. For these two product ids, the product.version is known to match the Eclipse release version (in general, that's not the case). This covers Eclipse 3.8 releases. For Juno, there were two parallel releases, 3.8 and 4.2. Those releases cannot be distinguished by their runtime.version, and platform.version isn't sent by those releases. However, the only official Eclipse.org releases for 3.8 were the two products listed here. For other product ids, the product.version is arbitrary and cannot be used to infer the Eclipse release version.
  3. Use runtime.version - Older release versions correspond to the major/minor version of the runtime plugin. Since the move to 4.x, this is no longer te case (i.e. Juno still had a runtime.version of 3.8.x and Kepler had a runtime.version of 3.9.x)

With the calculated release version, the release can be determined from the following mapping:

  • 4.5.x.xxx (Mars)
  • 4.4.x.xxx (Luna)
  • 4.3.x.xxx (Kepler)
  • 4.2.x.xxx (Juno)
  • 3.8.x.xxx (Eclipse 3.8 - parallel release to Juno)
  • 3.7.x.xxx (Indigo)
  • 3.6.x.xxx (Helios)
  • ...

If the calculated release version cannot be matched to an Eclipse release, no filtering will be performed.

Retrieving a listing of all catalogs

http://marketplace.eclipse.org/catalogs/api/p

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:

-Dorg.eclipse.epp.internal.mpc.core.service.DefaultCatalogService.url=http://mydomain.tld

This setting will request the url http://mydomain.tld/catalogs/api/p to obtain all available catalogs.


XML example

 <marketplace>
   <catalogs>
     <catalog id="38413" title="Eclipse Marketplace" url="http://mydomain.tld" selfContained="0" icon="http://marketplace.eclipse.org/sites/default/files/default_1_0.png">
       <description>Eclipse Marketplace (MP) is a place to find and keep track of Eclipse-based solutions.</description>
       <dependenciesRepository></dependenciesRepository>
       <wizard title="">
         <icon>http://marketplace.eclipse.org/sites/default/files/default_1.png</icon>
         <searchtab enabled="1">Search</searchtab>
         <populartab enabled="1">Popular</populartab>
         <recenttab enabled="1">Recent</recenttab>
         <news shorttitle="January 01/27" timestamp="1422334800">https://www.eclipse.org/community/eclipse_newsletter/2015/january/</news>
     </wizard>
   </catalog>
 </marketplace>
  • marketplace
    • catalogs
      • catalog
        • (@attribute) id: [int] Unique identifier
        • (@attribute) title: [string] Name of catalog
        • (@attribute) url: [string] Url prefix of the marketplace catalog
        • (@attribute) selfContained: [bool] TRUE/FALSE
        • (@attribute) icon: [string] Absolute url
        • description: [string] Short description
        • dependenciesRepository: [string]
        • wizard
          • (@attribute) title: [string] Title of Wizard
          • icon: [string] Absolute url
          • searchtab: [string] Search tab title
            • (@attribute) enabled: [bool] TRUE/FALSE
          • populartab: [string] Popular tab title
            • (@attribute) enabled: [bool] TRUE/FALSE
          • recenttab: [string] Recent tab title
            • (@attribute) enabled: [bool] TRUE/FALSE
          • news: [string] News content URL.
            • (@attribute) enabled: [bool] TRUE/FALSE

Retrieving A listing of Markets and Categories

http://marketplace.eclipse.org/api/p

This will return a listing of Markets and Categories, it includes URLs for each category, as well number of listings in each category.


XML example

 <marketplace>
   <market name="Tools" id="31" url="http://marketplace.eclipse.org/category/markets/tools">
     <category id="1964" count="158" url="http://marketplace.eclipse.org/taxonomy/term/1964%2C31" name="Application Development Frameworks" />
   </market>
   <market name="Long Term Support" id="3429" url="http://marketplace.eclipse.org/category/markets/long-term-support" />
 </marketplace>
  • marketplace
    • market
      • (@attribute) name: [string] Title
      • (@attribute) id: [int] Unique identifier
      • (@attribute) url: [string] Url
      • category (optional)
        • (@attribute) id: [int] Unique identifier
        • (@attribute) count: [int] Listing count
        • (@attribute) url: [string] Url
        • (@attribute) name: [string] Title

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.

http://marketplace.eclipse.org/taxonomy/term/4,31/api/p

These urls are easily obtained from using the http://marketplace.eclipse.org/api/p call.


XML example

 <marketplace>
   <category id="4" marketid="31" name="Build and Deploy" url="http://marketplace.eclipse.org/taxonomy/term/4%2C31">
     <node id="69" name="MyEclipse Enterprise Workbench" url="http://marketplace.eclipse.org/content/myeclipse-enterprise-workbench">
       <favorited>34</favorited>
       <installstotal>5394</installstotal>
       <installsrecent>0</installsrecent>
     </node>
   </category>
 </marketplace>
  • marketplace
    • category
      • (@attribute) id: [int] Unique identifier
      • (@attribute) marketid: [int] Unique identifier
      • (@attribute) name: [string] Title
      • (@attribute) url: [string] Url
      • node
        • (@attribute) id: [int] Unique identifier
        • (@attribute) name: [string] Listing Title
        • (@attribute) url: [string] Listing Url
        • favorited: [int] Number of times a listing was favorited
        • installstotal: [int] Install count
        • installsrecent: [int] Install count for the last month

Returning a Specific Listing

There are two methods of returning a specific listing.

http://marketplace.eclipse.org/content/[title]/api/p

and

http://marketplace.eclipse.org/node/[node id]/api/p

Calls to either URL will return a listing of contents of a node.


XML example

 <marketplace>
   <node id="29591" name="JRebel for Eclipse" url="http://mydomain.tld/content/example">
     <type>resource</type>
     <categories>
       <category id="4" name="Build and Deploy" url="http://mydomain.tld/category/categories/build-and-deploy" />
       <category id="24" name="IDE" url="http://mydomain.tld/category/categories/ide" />
       <category id="9" name="J2EE Development Platform" url="http://mydomain.tld/category/categories/j2ee-development-platform" />
       <category id="17" name="Tools" url="http://mydomain.tld/category/categories/tools" />
       <category id="20" name="Web" url="http://mydomain.tld/category/categories/web" />
     </categories>
     <tags>
       <tag id="134" name="J2EE" url="http://mydomain.tld/category/free-tagging/j2ee" />
       <tag id="327" name="eclipse" url="http://mydomain.tld/category/free-tagging/eclipse" />
       <tag id="422" name="java ee" url="http://mydomain.tld/category/free-tagging/java-ee" />
       <tag id="573" name="tools" url="http://mydomain.tld/category/free-tagging/tools" />
       <tag id="614" name="productivity" url="http://mydomain.tld/category/free-tagging/productivity" />
     </tags>
     <owner>Oliver White</owner>
     <favorited>66</favorited>
     <installstotal>0</installstotal>
     <installsrecent>140372</installsrecent>
     <shortdescription>SHORT DESCRIPTION</shortdescription>
     <body>LONG DESCRIPTION</body>
     <created>1295963961</created>
     <changed>1424896414</changed>
     <foundationmember>1</foundationmember>
     <homepageurl>http://www.zeroturnaround.com/software/jrebel/</homepageurl>
     <image>http://mydomain.tld/sites/all/themes/solstice/_themes/solstice_marketplace/public/images/default.png</image>
     <license>Commercial</license>
     <companyname>ZeroTurnaround</companyname>
     <status>Mature</status>
     <supporturl>http://www.zeroturnaround.com/jrebel/documentation/</supporturl>
     <version />
     <eclipseversion>4.5, 4.4, 4.3, 4.2, 4.1</eclipseversion>
     <updateurl>http://update.zeroturnaround.com/update-site</updateurl>
     <ius>
       <iu selected="TRUE">org.zeroturnaround.eclipse.feature</iu>
       <iu selected="TRUE">org.zeroturnaround.eclipse.wtp.feature</iu>
       <iu selected="TRUE">org.zeroturnaround.eclipse.m2e.feature</iu>
     </ius>
     <platforms>
       <platform>Windows</platform>
       <platform>Mac</platform>
       <platform>Linux/GTK</platform>
     </platforms>
   </node>
 </marketplace>
 
  • marketplace
    • node
      • (@attribute) id: [int] Unique identifier
      • (@attribute) name: [string] Listing Title
      • (@attribute) url: [string] Listing Url
      • type: [string] This is the type of listing being returned. 'training' is for a Training and Consulting Listing, 'resource' is for a solutions listing.
      • categories
        • (@attribute) id: [int] Unique identifier
        • (@attribute) name: [string] Title
        • (@attribute) url: [string] Url
      • owner: [string] Name of the author
      • favorited: [int] Number of times a listing was favorited
      • installstotal: [int] Install count
      • installsrecent: [int] Install count for the last month
      • shortdescription: [string] Listing teaser
      • body: [sting] Full description
      • created: [int] Timestamp
      • changed: [int] Timestamp
      • foundationmember: [bool] TRUE/FALSE
      • homepageurl: [string] Listing URL website
      • image: [string] Logo absolute URL
      • license: [string] Listing license
      • companyname: [string] Company name
      • status: [string] Release status
      • supporturl: [string] Support/documentation URL
      • version: [string] Version name
      • eclipseversion: [float] Eclipse release number (4.5, 4.4...)
      • updateurl: [string] Update site URL
      • ius: Feature ID's are used by the Eclipse Marketplace Client (MPC) to determine which features to install for your listing https://marketplace-staging.eclipse.org/feature-how-to
        • iu
          • (@attribute) required: [string] TRUE or FALSE
          • (@attribute) selected: [string] TRUE or FALSE
        • platforms
          • platform: [string] Compatible OS (Windows, Mac, Linux/GTK)

Examples

Returning Search Results

http://marketplace.eclipse.org/api/p/search/apachesolr_search/[query]?page_num=[page num]&filters=[filters]

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.

URL Variables


XML example

 <marketplace>
   <search term="test" url="http://marketplace-staging.eclipse.org/search/content/test" count="1">
     <node>Please refer to Returning a Specific Listing section.</node>
   </search>
 </marketplace>

Featured Listings

http://marketplace.eclipse.org/featured/api/p

This call will return a list of Featured Listings. By default this returns 6 listings. The default is configured on the server.

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.


http://marketplace.eclipse.org/featured/%/api/p

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.

Example:

XML example

 <marketplace>
   <featured count="10">
     <node>Please refer to Returning a Specific Listing section.</node>
   </featured>
 </marketplace>

Recently Updated Listings

http://marketplace.eclipse.org/recent/api/p

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.

XML example

 <marketplace>
   <recent count="10">
     <node>Please refer to Returning a Specific Listing section.</node>
   </recent>
 </marketplace>

Top Favorited Listings

http://marketplace.eclipse.org/favorites/top/api/p

This call will return a list of the Most Favorited Listings. By default this returns 6 listings. The default is configured on the server.

XML example

 <marketplace>
   <favorites count="10">
     <node>Please refer to Returning a Specific Listing section.</node>
   </favorites>
 </marketplace>

Most Popular Listings

http://marketplace.eclipse.org/popular/top/api/p

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.

XML example

 <marketplace>
   <popular count="10">
     <node>Please refer to Returning a Specific Listing section.</node>
   </recent>
 </marketplace>

Related Entries

http://marketplace.eclipse.org/related/api/p

This call will return a list of entries related to what's already installed in the running Eclipse. Installed entries are sent to the server as node ids in an additional query parameter

nodes: A list of space-separated node ids for installed marketplace nodes, url-encoded.

Example:

http://marketplace.eclipse.org/related/api/p?nodes=12345+23456+34567

This feature is already supported by the MPC client through a 'Related' tab that needs to be enabled in the catalog's branding information, see Catalog Description. The server at marketplace.eclipse.org does not yet support this query at the moment, see bug 453244.

Catalogs

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.

  1. Query the Base URL for a listing of Markets and their categories.
  2. Iterate through that query to retrieve listings for each category using the Category URL.
  3. Finally iterate through the Category Query to retrieve the data related to each node.

Catalog Description

Catalogs are managed through a registry on marketplace.eclipse.org. Each catalog is listed with its REST URL and branding information (Title, catalog icon, MPC wizard icon, supported MPC tabs).

A list of catalogs can be retrieved from http://marketplace.eclipse.org/catalogs/api/p

XML Example

  <marketplace>
    <catalogs>
      <catalog id="38413" title="Eclipse Marketplace" url="http://marketplace.eclipse.org" selfContained="0"
               icon="http://marketplace.eclipse.org/sites/default/files/marketplace_catalog_icon-32.png">
        <description>
          Eclipse Marketplace (MP) is a place to find and keep track of Eclipse-based solutions.
        </description>
        <dependenciesRepository/>
        <wizard title="">
          <icon>http://marketplace.eclipse.org/sites/default/files/marketplace_catalog_icon_0.png</icon>
          <searchtab enabled="1">Search</searchtab>
          <featuredmarkettab enabled="1">Eclipse Project</featuredmarkettab>
          <populartab enabled="1">Popular</populartab>
          <recenttab enabled="1">Recent</recenttab>
          <relatedtab enabled="1">Related</relatedtab>
          <news shorttitle="March 05/26" timestamp="1432612800">https://www.eclipse.org/community/eclipse_newsletter/2015/may</news>
        </wizard>
      </catalog>
    </catalogs>
  </marketplace>

News Page

Since MPC Kepler, it's 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

Marketplace Client

The Marketplace Client (MPC) project implements a client to the REST API. The client provides public Java API for accessing the REST API in the org.eclipse.epp.mpc.core plug-in through the classes in the org.eclipse.epp.mpc.core.service package.

Of interest to clients to the REST API:

  • IMarketplaceServiceLocator is an OSGi service that can be used as an entry point to access the catalog service and specific marketplace services.
  • IMarketplaceService gives access to the marketplace REST API
  • ICatalogService gives access to the catalog registry
  • The marketplace data model is available through interfaces in the org.eclipse.epp.mpc.model package.

In addition to the Java REST API, there is also some API to access the Marketplace Client wizard dialog in the org.eclipse.epp.mpc.ui plug-in:

  • MarketplaceClient offers some simple helper methods to open a wizard and to give access to the more elaborate IMarketplaceClientService
  • IMarketplaceClientService offers more elaborate configuration options to open a wizard in a specific state, e.g. with specific markets, entries preselected for install, or directly on the installation page.

Furthermore, 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.DefaultMarketplaceService A Java class that provides a Java API to the REST service
  • org.eclipse.epp.mpc.tests.service.DefaultMarketplaceServiceTest A JUnit test case that exercises the REST API

Back to the top