Requested changes to the Specs

[chrisguindon]

As discussed yesterday, this is the list of changes that are needed for the specs:

1. Sorting 1.1 Better define sort and & order. 1.2 Define whitelist of sortable fields: (installstotal, favorited, id, name, installsrecent, created, changed)

2. Listings 2.1 Include examples for the following MPC requests --- Recent call --- Most popular --- Top favourites --- Featured (Random) 2.2 We need to define the ability to retrieve multiple listings by id. Issue #18 2.3 add a search term parameter

3. Dates 3.1 We should be more explicit regarding the data format for all our response. Our Api style guides strongly recommend that date values conform to RFC 3339.

4. Installations 4.1 Create an array for the monthly numbers and create a new property for installsrecent + installstotal.

5. Catalog 5.1 We should return a url instead of a true or false for "searchtab", "populartab", "recenttab", "news".

6. General feedback 6.1 Some call don't include a description. Please make sure that we have text describing each call. For example https://eclipsefdn.github.io/marketplace-rest-api-specs/#/paths/~1catalogs/get 6.3 Describe how the pagination will work 6.4 Confirm with MPC team that we are dropping the following parameters: client, client.version, product, ws, platform.version 6.5 Make sure that spec adheres to our API best practices:

7. API best practices (Please refer to the document for the full list of BP) 7.1 JSON Guidelines --- Property names must be ASCII snakecase (and never camelCase): ^[a-z][a-z_0-9]*$ --- Array names should be pluralized --- Boolean property values must not be null --- Null values should have their fields removed --- Empty array values should not be null --- Date property values should conform to RFC 3339 7.2 API Naming --- Use lowercase separate words with hyphens for Path Segments --- Use snakecase (never camelCase) for Query Parameters --- Prefer Hyphenated-Pascal-Case for HTTP header Fields --- Pluralize Resource Names --- Not Use /api as Base Path --- Avoid Trailing Slashes --- Stick to Conventional Query Parameters ---- q ---- sort ---- fields ---- embed ---- offset ---- cursor ---- limit 7.3 Resources --- Use URL-friendly Resource Identifiers: [a-zA-Z0-9:.-] --- Identify resources and Sub-Resources via Path Segments --- Everything is a resource, avoid actions ---- Keep URLs Verb-Free --- resource should contain as much information as necessary, but as little as possible

[chrisguindon]

We should also include the ranking in a listing response. This was requested via issue #3

[chrisguindon]

Since we are here, I think we should also rename some parameters.

In issue #8, I am asking if we should rename product.version to eclipse_release. I think we should do the same for java.version and rename it to min_java_version.

If we do so, we should require folk to set a numeric value for min_java_version such as 6,7,8,9...

[autumnfound]

We should maintain the 1.# format for the time being for min_java_version, as there has been talk in the past of moving away from the current version model to something less pretty (https://mreinhold.org/blog/forward-faster).

e.g. A release this September would become 19.09 under what is mentioned in that blog

[chrisguindon]

Remaining changes:

• Authors should be an array:

"authors": {
  {
    "username:" "webdev", 
    "full_name": "Christopher Guindon" 
  },
  {
    "username": "test", 
    "full_name": "Test test" 
  }
}

• Create a solution version array with the following properties:

"solution_versions": {
  "version": "string",
  "update_site_url" "string",
  "eclipse_version": {"4.5", "4.6"},
  "platform": {},
  "min_java_version": "string",
  "feature_ids": {
    "feature_id:": "string",
    "install_state": "string" ("optional", "required", "optional_selected" )
  }
}

• organization should be an array:

  
  "organization": {
  "id": 324
  "name": "Eclipse Foundation"
  }