Requested changes to the Specs

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 snake_case (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 snake_case (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