Requested changes to the Specs #19

Current progress on API spec based on the feedback.

Change-Id: I82ce479554d8ad97570c88ea3429d5b9d2d21a98 Signed-off-by: Martin Lowe martin.lowe@eclipse-foundation.org

spec/openapi.yaml

@@ -10,17 +10,32 @@ info:
servers:
- url: http://marketplace.eclipse.org/api/v2
description: Production endpoint for Eclipse Marketplace API
-
+tags:
+  - name: Listings
+    description: Definitions for marketplace listings and their versions
+  - name: Catalogs
+    description: Marketplace catalog definitions
+  - name: Categories
+    description: Market categories
+  - name: Installs
+    description: Access to listing install stats
+  - name: Markets
+    description: Information about available markets
paths:
/listings:
-    get: 
+    get:
+      tags:
+        - Listings
summary: Listing list
+      description: Returns a list of marketplace listings that match the given parameters, filtering out solutions that don't match the filters.
parameters:
-        - $ref: "#/components/parameters/product.version"
-        - $ref: "#/components/parameters/runtime.version"
-        - $ref: "#/components/parameters/java.version"
+        - $ref: "#/components/parameters/product_version"
+        - $ref: "#/components/parameters/runtime_version"
+        - $ref: "#/components/parameters/java_version"
- $ref: "#/components/parameters/os"
- $ref: "#/components/parameters/locale"
+        - $ref: "#/components/parameters/page"
+        - $ref: "#/components/parameters/page_size"
- name: marketID
in: query
description: "The ID of the market to search in for listings"
@@ -33,7 +48,7 @@ paths:
required: false
schema:
$ref: "#/components/schemas/ObjectID"
-        - name: licenseType
+        - name: license_type
in: query
description: |
Optional query parameter to filter the results by license type.
@@ -48,20 +63,42 @@ paths:
* GPL
required: false
schema:
-            $ref: "#/components/schemas/licenseType"
+            $ref: "#/components/schemas/license_type"
style: form
explode: true
- name: sort
in: query
-          description: Optional query parameter to sort the resulting listings. This sort will be performed based on the field name passed, leaving the values unsorted if there is no field name that matches
+          description: |
+            Optional query parameter to sort the resulting listings. This sort will be performed based on the field name passed, in either ascending or descending order based on which of ASC or DESC was passed after the field name separated by a space. 
+             
+            At this time, only a subset of whitelisted values are enabled for sorting, and only one of which can be used for sorting at a time. See below for a list of accepted fields.
+            
+            - installs_total
+            - favorited
+            - id
+            - name
+            - installs_recent
+            - created
+            - changed
+            
+            This value should be in the format of `fieldname [ASC|DESC]`. For example, `installsrecent DESC`
required: false
schema:
type: string
-        - name: order
+        - name: featured
in: query
-          description: Optional query parameter to order the resulting listings. This sort will be performed based on the field name passed, leaving the values unsorted if there is no field name that matches
-          required: false
+          description: If set to true, will randomize results based on a random seed and ignore sort clauses.
schema:
+            type: boolean
+        - name: q
+          in: query
+          description: Search term to use when narrowing down results.
+          schema:
+            type: string
+        - name: ids
+          in: query
+          description: Comma-delimited list of listing IDs to retrieve for the call.
+          schema:
type: string
responses:
200:
@@ -73,7 +110,10 @@ paths:
500:
description: Error while retrieving data
put:
+      tags:
+        - Listings
summary: Listing update
+      description: Using the passed listing object, updates, or in the case of new data inserts, are made in the data set to include the new information.
requestBody:
description: The listing to be updated or inserted into the data set.
content:
@@ -102,13 +142,16 @@ paths:
type: integer
format: int32
minimum: 1
-      - $ref: "#/components/parameters/product.version"
-      - $ref: "#/components/parameters/runtime.version"
-      - $ref: "#/components/parameters/java.version"
+      - $ref: "#/components/parameters/product_version"
+      - $ref: "#/components/parameters/runtime_version"
+      - $ref: "#/components/parameters/java_version"
- $ref: "#/components/parameters/os"
- $ref: "#/components/parameters/locale"
get:
+      tags:
+        - Listings
summary: Listing
+      description: Returns a single listing that has a matching listing ID, filtering out versions that do not match the passed parameters.
responses:
200:
description: Success
@@ -131,12 +174,16 @@ paths:
type: integer
format: int32
minimum: 1
-      - $ref: "#/components/parameters/product.version"
-      - $ref: "#/components/parameters/java.version"
+      - $ref: "#/components/parameters/product_version"
+      - $ref: "#/components/parameters/java_version"
- $ref: "#/components/parameters/os"
- $ref: "#/components/parameters/locale"
- $ref: "#/components/parameters/country"
+      - $ref: "#/components/parameters/page"
+      - $ref: "#/components/parameters/page_size"
get:
+      tags:
+        - Installs
summary: Installation list by Listing
description: Retrieve install metrics for marketplace a listing by its unique ID. These stats will include available metrics for the last 12 months, as well as the overall install statistics. The parameters that are available for this call act as filters for the statistics, allowing for greater flexibility of analysis of the Installation stats.
responses:
@@ -168,12 +215,16 @@ paths:
format: float
minimum: 0
get:
+      tags:
+        - Installs
parameters:
-        - $ref: "#/components/parameters/product.version"
-        - $ref: "#/components/parameters/java.version"
+        - $ref: "#/components/parameters/product_version"
+        - $ref: "#/components/parameters/java_version"
- $ref: "#/components/parameters/os"
- $ref: "#/components/parameters/locale"
- $ref: "#/components/parameters/country"
+        - $ref: "#/components/parameters/page"
+        - $ref: "#/components/parameters/page_size"
description: Retrieve install metrics for the given marketplace listing and version by its unique listing ID and version number. These stats will include available metrics for the last 12 months, as well as the overall install statistics for the version. The parameters that are available for this call act as filters for the statistics, allowing for greater flexibility of analysis of the Installation stats.
summary: Installation list by Solution Version
responses:
@@ -186,6 +237,8 @@ paths:
404:
description: Invalid listing and version combination, no data found
post:
+      tags:
+        - Installs
summary: Create Installation
description: Add information about an install. (Only accessible via the marketplace client)
responses:
@@ -195,9 +248,13 @@ paths:
description: Forbidden
404:
description: Invalid listing and version combination, no data found
+
/catalogs:
get:
+      tags:
+        - Catalogs
summary: Catalog list
+      description: Retrieves information about the catalogs available in the marketplace.
responses:
200:
description: Success
@@ -208,7 +265,10 @@ paths:
500:
description: Error while retrieving data
put:
+      tags:
+        - Catalogs
summary: Catalog update
+      description: Add or update information about a catalog in the marketplace.
requestBody:
description: The catalog to be updated or inserted into the data set.
content:
@@ -238,7 +298,10 @@ paths:
format: int32
minimum: 1
get:
+      tags:
+        - Catalogs
summary: Catalog
+      description: Retrieve information on a single catalog, matching on the catalog ID.
responses:
200:
description: Success
@@ -253,7 +316,13 @@ paths:
/markets:
get:
+      tags:
+        - Markets
summary: Market list
+      description: Retrieves a listing of markets available within the marketplace.
+      parameters:
+        - $ref: "#/components/parameters/page"
+        - $ref: "#/components/parameters/page_size"
responses:
200:
description: Success
@@ -264,7 +333,10 @@ paths:
500:
description: Error while retrieving data
put:
+      tags:
+        - Markets
summary: Market update
+      description: Add or update information about a market in the marketplace.
requestBody:
description: The market to be updated or inserted into the data set.
content:
@@ -294,7 +366,10 @@ paths:
format: int32
minimum: 1
get:
+      tags:
+        - Markets
summary: Market
+      description: Retrieve a single market within the marketplace, matching on its ID.
responses:
200:
description: Success
@@ -323,8 +398,13 @@ paths:
type: integer
format: int32
minimum: 1
+      - $ref: "#/components/parameters/page"
+      - $ref: "#/components/parameters/page_size"
get:
+      tags:
+        - Categories
summary: Category by Market
+      description: Retrieves a category in context of its market in the marketplace. 
responses:
200:
description: Success
@@ -337,7 +417,13 @@ paths:
/categories:
get:
+      tags:
+        - Categories
+      parameters:
+        - $ref: "#/components/parameters/page"
+        - $ref: "#/components/parameters/page_size"
summary: Category list
+      description: Retrieves a listing of categories available within the marketplace.
responses:
200:
description: Success
@@ -348,7 +434,10 @@ paths:
500:
description: Error while retrieving data
put:
+      tags:
+        - Categories
summary: Category update
+      description: Add or update information about a category in the marketplace.
requestBody:
description: The market to be updated or inserted into the data set.
content:
@@ -361,7 +450,7 @@ paths:
content:
application/json:
schema:
-                $ref: "#/components/schemas/Catalog"
+                $ref: "#/components/schemas/Category"
201:
description: Success (no content)
500:
@@ -378,14 +467,17 @@ paths:
format: int32
minimum: 1
get:
+      tags:
+        - Categories
summary: Catagory
+      description: Retrieves a category available within the marketplace, matched on its ID.
responses:
200:
description: Success
content:
application/json:
schema:
-                $ref: "#/components/schemas/Catalog"
+                $ref: "#/components/schemas/Category"
404:
description: Not found
500:
@@ -400,22 +492,22 @@ components:
required: false
schema:
type: string
-    product.version:
-      name: product.version
+    product_version:
+      name: product_version
in: query
description: The version of the running product of the target Eclipse, identical to the version of the product's branding plugin
required: false
schema:
$ref: "#/components/schemas/osgiVersion"
-    runtime.version:
-      name: runtime.version
+    runtime_version:
+      name: runtime_version
in: query
description: The version of the org.eclipse.core.runtime bundle of the target Eclipse
required: false
schema:
$ref: "#/components/schemas/osgiVersion"
-    java.version:
-      name: java.version
+    java_version:
+      name: java_version
in: query
description: The version of the JRE running the target Eclipse, as returned by the JRE's `System.getProperty("java.version")`
required: false
@@ -449,6 +541,20 @@ components:
required: false
schema:
type: string
+    page:
+      name: page
+      in: query
+      description: The current page in pagination for results
+      required: false
+      schema:
+        type: integer
+    page_size:
+      name: page_size
+      in: query
+      description: 'The size of result sets returned (maximum: 50, default: 10)'
+      required: false
+      schema:
+        type: integer
schemas:
Listing:
@@ -475,13 +581,13 @@ components:
favorited:
type: integer
description: Number of times a listing was favorited
-        installstotal:
+        installs_total:
type: integer
description: Install count
-        installsrecent:
+        installs_recent:
type: integer
description: Install count for the last month
-        shortdescription:
+        short_description:
type: string
description: Listing teaser
body:
@@ -493,10 +599,10 @@ components:
changed:
type: integer
description: Timestamp
-        foundationmember:
+        foundation_member:
type: boolean
description: TRUE/FALSE
-        homepageurl:
+        homepage_url:
type: string
description: Listing URL website
image:
@@ -505,25 +611,28 @@ components:
license:
type: string
description: Listing license
-        companyname:
+        company_name:
type: string
description: Company name
status:
type: string
description: Release status
-        supporturl:
+        support_url:
type: string
description: Support/documentation URL
version:
type: string
description: Version name
-        eclipseversion:
+        eclipse_version:
type: number
format: float
description: Eclipse release number (4.5, 4.4...)
-        updateurl:
+        update_url:
type: string
description: Update site URL
+        ranking:
+          type: string
+          description: Relative ranking of the given listing.
ius:
type: array
items:
@@ -555,7 +664,7 @@ components:
name:
type: string
description: Tag Title
-        URL:
+        url:
type: string
description: URL to retrieve the tag details.
@@ -572,10 +681,10 @@ components:
name:
type: string
description: Category title
-        URL:
+        url:
type: string
description: URL to retrieve the category details.
-        marketIDs: 
+        market_ids: 
type: array
items:
$ref: "#/components/schemas/ObjectID"
@@ -624,7 +733,7 @@ components:
url:
type: string
description: Url prefix of the marketplace catalog
-        selfContained:
+        self_contained:
type: boolean
description: TRUE/FALSE
icon:
@@ -633,22 +742,22 @@ components:
description:
type: string
description: Short description
-        dependenciesRepository:
+        dependencies_repository:
type: string
-        searchtab:
-          type: boolean
-          description: TRUE/FALSE 
-        populartab:
-          type: boolean
-          description: TRUE/FALSE 
-        recenttab:
-          type: boolean
-          description: TRUE/FALSE 
+        search_tab:
+          type: string
+          description: URL to populate tab if it exists, or empty 
+        popular_tab:
+          type: string
+          description: URL to populate tab if it exists, or empty 
+        recent_tab:
+          type: string
+          description: URL to populate tab if it exists, or empty 
news:
type: boolean
description: TRUE/FALSE
-    licenseType:
+    license_type:
type: string
enum:
- COMMERCIAL # Includes all commercial license types
@@ -658,28 +767,54 @@ components:
- EPL 2.0
- GPL
+    sort_whitelist:
+      type: string
+      enum:
+        - installs_total
+        - favorited
+        - id
+        - name
+        - installs_recent
+        - created
+        - changed
+
osgiVersion:
type: number
format: float
description: Describes the version of OSGi the given platform is using
Installs:
-      type: array
-      minItems: 13
-      items:
-        type: object
-        properties:
-          start:
-            type: string
-            format: datetime
-            description: Start date for the range of counted installs
-          end: 
-            type: string
-            format: datetime
-            description: End date for the range of counted installs
-          count:
-            description: Number of installs in the given period for the given version
-            type: integer
-            format: int32
-            minimum: 0 
+      type: object
+      properties:
+        monthly_stats:
+          type: array
+          minItems: 11
+          items:
+            type: object
+            properties:
+              start:
+                type: string
+                format: datetime
+                description: |
+                  Start date for the range of counted installs in RFC 3339 format. Example, `1990-12-31T15:59:60-08:00`.
+                  
+                  More on this standard can be read at https://tools.ietf.org/html/rfc3339.
+              end: 
+                type: string
+                format: datetime
+                description: End date for the range of counted installs
+              count:
+                description: |
+                  Number of installs in the given period for the given version in RFC 3339 format. Example, `1990-12-31T15:59:60-08:00`.
+                  
+                  More on this standard can be read at https://tools.ietf.org/html/rfc3339.
+                type: integer
+                format: int32
+                minimum: 0 
+        installs_recent:
+          type: number
+          description: The number of installs in the last month for the given resource
+        installs_total:
+          type: number
+          description: The number of historic installs for the given resource
\ No newline at end of file