Very basic question about resources


#1

Very basic 2 questions about resources.

  1. What the /: mean ?
  2. What the /{invoice-id}: mean ?

#2

In the case of a URL, the / is a path separator that you can use to direct an API request to. It allows you to separate resources much like name spacing in a language does.

The /{whatever} refers to a path parameter. In your example, I would assume the first part of the path might be something like http://server.com/invoices which the noun invoices refers to the collection of invoices. A GET to this resource would typically result in a response of ALL invoices your service provides (e.g. invoice data in the DB). That data would be 0 or more records, probably in JSON or XML form, with some number of properties and values and maybe other data structures. In there, given your 2nd question, we would assume an ID property is provided. With that, we can do a GET /invoices/{id} to get a specific invoice resource. This reduces the amount of data over the wire to a single entry rather than the entire collection. It would also perhaps allow you to update the individual resource, delete it, etc using the ID.

In the context of resources, typical a /collection/{invidivdual of collection} format is used (but not always) and the {id} in this case is referred to as a sub-resource… or a subset of the overall collection. You will also often see filtering and pagination options on a collection resource, to help reduce the total result set to a “SUBset”. These are usually in the form of query parameters.

Does that help?


#3

In short /: is represented as the resource path and the resource can be requested using /: in the API, where as /{invoice-id}: represent a parameter or a dynamic value in the path.
In API we use parameter to pass our dynamic value while calling a resources.
The specification link can make it more clear : - https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md