From 369c37daca09f5fee81b24904d26065b318ec7b4 Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Wed, 16 Sep 2020 16:52:18 +1000 Subject: [PATCH 1/4] Naming Conventions - De-Preference Case Update to naming-conventions.md to de-preference case, issues #23, #34, #40 --- sections/naming-conventions.md | 51 +++++++++++++++------------------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/sections/naming-conventions.md b/sections/naming-conventions.md index 72935a4..01214bd 100644 --- a/sections/naming-conventions.md +++ b/sections/naming-conventions.md @@ -3,31 +3,26 @@ ______________________________________________________________________________ ## Message Format -For request and response body and query parameter names the message format is **RECOMMENDED** to use snake-case: +For request and response body field names and query parameter names case **MUST** be consistent, and **SHOULD** be either camelCase OR snake_case: -Example: - -```javascript -// this_is_snake_case +Examples: +``` +// thisIsCamelCase { - "employee_id" : "AB1837" + "employeeId" : "AB1837" } ``` - -If snake-case is not available, it is then **RECOMMENDED** to use camel case. - -Example: - -```javascript -// thisIsCamelCase +``` +// this_is_snake_case { - "employeeId" : "AB1837" + "employee_id" : "AB1837" } ``` -In either case the object and field definition must be the same for the request and response body and query parameters. +Fields that represent arrays **SHOULD** be named using plural nouns (e.g. products - contains one or more products). +The object and field definition **MUST** be the same for the request and response body as well as corresponding query parameter values. ## URI Component Names @@ -43,7 +38,7 @@ URLs **MUST** follow the standard naming convention as described below: ``` - https://gw.api.gov.au/namespace/project-name/v1/collection?attributes=first_name,last_name + https://gw.api.gov.au/namespace/project-name/v1/collection?fields=first_name,last_name \___/ \___________/\___________________________________/\______________________________/ | | | | scheme authority path query @@ -59,7 +54,7 @@ URLs **MUST** follow the standard naming convention as described below: - the URI **MUST** be specified in all lower case - only hyphens '-' can be used to separate words or path parameters for readability (no spaces or underscores) -- only underscores '\_' can be used to separate words in query parameter names but not as part of the base URI +- underscores '\_' or camelCase can be used to separate words in query parameter names but not as part of the base URI The following table provides a breakdown of how to construct the API URI. @@ -82,12 +77,12 @@ API Designers **MUST** follow these principles when creating a REST API: - Resource names **MUST** be lower-case and use only alphabetic characters and hyphens. - The hyphen character, ( - ), MUST be used as a word separator in URI path parameters. -**Note** that this is the only place where hyphens are used as a word separator. In nearly all other situations the underscore character, ( _ ), **MUST** be used. +**Note** that this is the only place where hyphens are used as a word separator. In nearly all other situations camelCase OR an underscore character, ( _ ), **MUST** be used. Good examples: - `/employees` -- `/customers` +- `/sea-cargo` - `/products` Bad examples: @@ -99,8 +94,8 @@ Bad examples: ### Query Parameter Names - Literals/expressions in query strings **SHOULD** be separated using underscore ( _ ). -- Query parameters values **MUST** be percent-encoded. -- Query parameters **MUST** start with a letter and **SHOULD** be all in lower case. Only alpha characters, digits and the underscore ( _ ) character **SHALL** be used. +- Query parameters values **MUST** be percent-encoded. Where possible, for portability and compatability reasons, values SHOULD be restricted to the AWS supported query paramter regex ^[a-zA-Z0-9._$-]+$ +- Query parameters **MUST** start with a letter and **SHOULD** be either camelCase or snake_case, consistent with the case standard employed for field names. - Query parameters **SHOULD** be optional. - Query parameters **SHOULD** not contain characters that are not URL safe. @@ -110,17 +105,17 @@ The data model for the representation **MUST** conform to the `JSON` specificati The values may themselves be objects, strings, numbers, booleans, or arrays of objects. -- Key names MUST be lower-case words, separated by an underscore character, ( _ ). +- Key names MUST be either camelCase or snake_case, however case MUST be used consistently. - `foo` - - `bar_baz` -- Prefix such as `is_` or `has_` **SHOULD NOT** be used for keys of type boolean. + - `barBaz` OR `bar_baz` +- Prefix such as `is` or `has` **SHOULD NOT** be used for keys of type boolean. - Fields that represent arrays **SHOULD** be named using plural nouns (e.g. authenticators-contains one or more authenticators, products-contains one or more products). ## Link Relation Names To help guide users through your API relational links **MUST** be provided. These links act as the navigation of your API advising users of where they can go to next. -A `_links` array **MUST** be provided for resources. This contains link objects that can refer to related resources in the system. +A `_links` array **SHOULD** be provided for resources. This contains link objects that can refer to related resources in the system. A link relation **MUST** contain the following elements: @@ -206,11 +201,11 @@ To represent Australian Eastern Standard time (+10), the following format would When using date fields, the following naming conventions for these fields should be used: -- For properties requiring both date and time, services **MUST** use the suffix `datetime`, e.g. `start_datetime`. +- For properties requiring both date and time, services **MUST** use the suffix `datetime`, e.g. `startDateTime` | `start_datetime`. -- For properties requiring only date information without specifying time, services **MUST** use the suffix `date`, e.g. `birth_date`. +- For properties requiring only date information without specifying time, services **MUST** use the suffix `date`, e.g. `birthDate` | `birth_date`. -- For properties requiring only time information without specifying date, services **MUST** use the suffix `time`, e.g. `appointment_start_time`. +- For properties requiring only time information without specifying date, services **MUST** use the suffix `time`, e.g. `startTime` | `start_time`. ## Examples From 4c37e0c35147680f2bff4122566e11a8105d3ce0 Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Thu, 24 Sep 2020 12:24:42 +1000 Subject: [PATCH 2/4] Update naming-conventions.md --- sections/naming-conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/naming-conventions.md b/sections/naming-conventions.md index 01214bd..2867ad3 100644 --- a/sections/naming-conventions.md +++ b/sections/naming-conventions.md @@ -38,7 +38,7 @@ URLs **MUST** follow the standard naming convention as described below: ``` - https://gw.api.gov.au/namespace/project-name/v1/collection?fields=first_name,last_name + https://gw.api.gov.au/namespace/project-name/v1/collection?fields=firstName,lastName \___/ \___________/\___________________________________/\______________________________/ | | | | scheme authority path query @@ -66,7 +66,7 @@ The following table provides a breakdown of how to construct the API URI. | 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/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

+| Query String \> Parameters | 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. `fields=first_name,last_name` returns data element with only the `first_name` and `last_name` attributes

`filter=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 From 9124f264b0e42c778d06d7c3a8919d5a61e9ddb9 Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Thu, 24 Sep 2020 13:26:17 +1000 Subject: [PATCH 3/4] Update naming-conventions.md Update to provide OData filter syntax example --- sections/naming-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/naming-conventions.md b/sections/naming-conventions.md index 2867ad3..0c893d8 100644 --- a/sections/naming-conventions.md +++ b/sections/naming-conventions.md @@ -66,7 +66,7 @@ The following table provides a breakdown of how to construct the API URI. | 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/E13454` | -| Query String \> Parameters | 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. `fields=first_name,last_name` returns data element with only the `first_name` and `last_name` attributes

`filter=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

+| Query String \> Parameters | 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. `fields=first_name,last_name` returns data element with only the `first_name` and `last_name` attributes

`filter=creation_date gt 2001-09-20T13:00:00 and creation_date le 2001-09-21T13:00:00 and and post_code eq 3000` - return a collection of resources where the creation date is greater than 2001-09-20 1pm and less than or equal to 2001-09-21 1pm 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 From 3841bb6386e0e683e8c4fa00b956e981cf0e4940 Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Mon, 28 Sep 2020 09:48:50 +1000 Subject: [PATCH 4/4] Update to naming-conventions.md error correction --- sections/naming-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/naming-conventions.md b/sections/naming-conventions.md index 0c893d8..3668437 100644 --- a/sections/naming-conventions.md +++ b/sections/naming-conventions.md @@ -94,7 +94,7 @@ Bad examples: ### Query Parameter Names - Literals/expressions in query strings **SHOULD** be separated using underscore ( _ ). -- Query parameters values **MUST** be percent-encoded. Where possible, for portability and compatability reasons, values SHOULD be restricted to the AWS supported query paramter regex ^[a-zA-Z0-9._$-]+$ +- Query parameters values **MUST** be percent-encoded. Consider that AWS requires query paramter names to conform to the regex ^[a-zA-Z0-9._$-]+$ - Query parameters **MUST** start with a letter and **SHOULD** be either camelCase or snake_case, consistent with the case standard employed for field names. - Query parameters **SHOULD** be optional. - Query parameters **SHOULD** not contain characters that are not URL safe.