[Query or Metrix in URL] #REST

QueryParamOrMetrixParam.md

• URL with ? are not cached in many cases
• URL with matrix params are cached
• Metrix param can appear everywhere in the path and are not limited to its end
• Metrix param can have more than one value, e.g. paramA=val1,val2
• Metrix param is used when it's hard to structure a hierarchy in URL

Example

Scenario 1: find the first page of objects in multiple categories:

• the object name is green (it might match multiple ones)
• the object is in category with name foo (it might match multiple ones)

Example data:

• (cateId-1: foo) -> (objId-1: green)
• (cateId-2: foo) -> (objId-2: green)
• (cateId-2: foo) -> (objId-3: green)

GOOD: http://example.com/res/categories;name=foo/objects;name=green/?page=1

BAD: http://example.com/res/categories/objects?categoryName=foo&objectName=green&page=1

WORSE:http://example.com/res/categories/foo/objects/green&page=1

Scenario 2: Yearly query + filtering

We define /books/{year} since we only support query data in a year period per API call.

How do we filter by book's auther?

• Good, but not cacheable: /books/2012?author=andin
• Better, cacheable, and more readable: /books/2012;author=andin

Why not /books/2012/andin?

• Could be good pattern, only if you 100% sure key use case is "query by year, and by auther"
• More {} in path, the path will be more fragile
• It's impossible to simply list them all in URL path.