Help with actions...

[sheshmantha]

Hi, I'm having a hard time figuring out the structure of the apib to create for an API I have. In one group, I have two apis:

/recommendations/similarTo/titles/titleID{,titleid2,titleid3...}{?limit=25}
/recommendations/topTrending/{?limit=25&time=24h}

I've tried various ways of defining them in api-blueprint syntax and am unable to get the Actions properly.

Here is one version that I have... (seems pretty botched up) -- clearly I'm missing something.

# Group Recommendations
This is a group. ```recommendations``` are a first class resource in my API.

The structure of the Recommendations APIs is:
```/recommendations/{action}/{particulars}```
where ```{action}``` can be the action that needs to be taken and ```{particulars}``` are necessary and optional elements to execute that action.

## Recommendations [/recommendations]
hello world

### Similar To [/recommendations/similarTo]
this is similar to

#### SimilarTo [GET /recommendations/similarTo/titleID?limit=25]
Get titles that are similar to one or more titles

+ Parameters
  + titleID: `crid:~~2fblah` (string, required) - ID of the title
  + titleID2: `crid:~~2fblah2` (string, optional) - ID of another title
  + limit: `25` (number, optional) - Number of recommendations to return
    + Default: `20`

+ Response 200 (application/json)

        {
          "resultCount": 2,
          "similarTitles": [
          {
            "id": "crid:~~2F~~2Fadrenalin.schange.com~~2Fasset0123456"
          }]
        }

Could someone please advise ??

[pksunkara]

Unfortunately, we cannot support variable uri path parameters yet. So the {particulars} section of your API will be hard to write in the API Blueprint. Also a good practice for API is that you should send the particulars` as a part of query parameters instead of in the path.

# Group Recommendations

#### SimilarTo [GET /recommendations/similarTo/{titleID}/{titleID2}?limit]
Get titles that are similar to one or more titles

+ Parameters
  + titleID: `crid:~~2fblah` (string, required) - ID of the title
  + titleID2: `crid:~~2fblah2` (string, optional) - ID of another title
  + limit: `25` (number, optional) - Number of recommendations to return
    + Default: `20`

+ Response 200 (application/json)

        {
          "resultCount": 2,
          "similarTitles": [
          {
            "id": "crid:~~2F~~2Fadrenalin.schange.com~~2Fasset0123456"
          }]
        }