diff --git a/sections/naming-conventions.md b/sections/naming-conventions.md index 8e6572b..72935a4 100644 --- a/sections/naming-conventions.md +++ b/sections/naming-conventions.md @@ -70,7 +70,7 @@ The following table provides a breakdown of how to construct the API URI. | Path \> API | The API name which is derived from the business domain. | e.g. `/namespace/project-name`
Any agency/department can specify the API name that they would like to expose their services on. | | Path \> Version | The version of the API that is desired to be accessed by the consumer. | e.g. `/v1`
All APIs must specify a version that follow the versioning scheme as specified in 'versioning' below. | | Path \> Collection | The collection identifies a list of resources. The collection **MUST** be named using the **plural** representation of a noun. | e.g. As part of the workforce API - a resource could be a list of `employees`. | -| Path \> Resource | The resource identifier which corresponds to an instance of the resource. | e.g. As part of the **project-name** API - if there was a specific employee with id E13454. These details can be retrieved using `GET` `/project-name/v1/employees/E13455` | +| Path \> Resource | The resource identifier which corresponds to an instance of the resource. | e.g. As part of the **project-name** API - if there was a specific employee with id E13454. These details can be retrieved using `GET` `/project-name/v1/employees/E13454` | | Query String \> Parameters/Filters | Query parameters **MUST** NOT be used to transport payload or actual data.
The following query parameters **SHOULD** be supported by your API where they would be useful: | e.g. `attributes=first_name,last_name` returns data element with only the `first_name` and `last_name` attributes

`filters=creation_date => 2001-09-20T13:00:00 and creation_date <= 2001-09-21T13:00:00 and first_name like 'fred' and post_code=3000` - return a collection of resources where the creation date is between 2001-09-20 1pm and 2001-09-21 1pm and first-name like 'fred' and post_code is 3000.

`sort=date_of_birth desc` - return a collection where the resources are sorted by date_of_birth in descending order.

`page=10` – returns the 10th page index

### Resource Names @@ -212,6 +212,9 @@ When using date fields, the following naming conventions for these fields should - For properties requiring only time information without specifying date, services **MUST** use the suffix `time`, e.g. `appointment_start_time`. +## Examples + +### Good URL examples List of employees:
`GET` https://gw.api.gov.au/e09284/v1/employees
@@ -231,16 +234,16 @@ Add a new location to a particular employee:
Non-plural endpoint: - https://gw.api.vic.gov.au/e09284/v1/employee
- https://gw.api.vic.gov.au/e09284/v1/employee/1234
- https://gw.api.vic.gov.au/e09284/v1/employee/1234/location
+ `GET` https://gw.api.vic.gov.au/e09284/v1/employee
+ `GET` https://gw.api.vic.gov.au/e09284/v1/employee/1234
+ `GET` https://gw.api.vic.gov.au/e09284/v1/employee/1234/location
- https://gw.api.gov.au/e09284/v1/employee
- https://gw.api.gov.au/e09284/v1/employee/1234
- https://gw.api.gov.au/e09284/v1/employee/1234/location
+ `GET` https://gw.api.gov.au/e09284/v1/employee
+ `GET` https://gw.api.gov.au/e09284/v1/employee/1234
+ `GET` https://gw.api.gov.au/e09284/v1/employee/1234/location
Verb in the URL:
- https://gw.api.gov.au/e09284/v1/employee/1234/create
+ `POST` https://gw.api.gov.au/e09284/v1/employee/1234/create
Filtering outside in the URL instead of the query string
- https://gw.api.gov.au/e09284/v1/employee/1234/desc
+ `GET` https://gw.api.gov.au/e09284/v1/employee/1234/desc