When to use pathParams or QueryParams

Question

Is there a rule of thumb as to when one should use path parameters for a URL versus when you should use query parameters?

Say I've got a table Invoice with the fields company(PK),InvoiceNo(PK), Invoiceline, invoiceValue, noOfLines, salesPerson

My current thinking is that your URL should be along the lines of

/Invoice/

Which would display all invoices

/Invoice/{company}

Which would display all invoices for the company.

/Invoice/{company}/{InvoiceNo}

Displays that specific invoice and

/Invoice/{company}/{InvoiceNo}?invoiceLineNo=23

displays only line 23.

The way I'm thinking is that Primary key fields should be part of the path and any other fields that you would filter on are part of the query parameter.

Does this sound like a reasonable way of distinguishing between the two?

Answer 1

My personal rule of thumb that the PathParam leads upto the entity type that you are requesting.

/Invoices             // all invoices
/Invoices?after=2011  // a filter on all invoices

/Invoices/52          // by 52
/Invoices/52/Items    // all items on invoice 52
/Invoices/52/Items/1  // Item 1 from invoice 52

/Companies/{company}/Invoices?sort=Date
/Companies/{company}/Invoices/{invoiceNo} // assuming that the invoice only unq by company?

To quote Mr Rowe: Path parameters for grouping data, query parameters for filtering