From ae50bd62552994cbce7d1d907f37879aa4056732 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Thu, 19 Sep 2024 22:59:20 +0200 Subject: [PATCH 1/2] Add: GraphQL pagination to Decision Records --- DEVELOPMENT_DECISION_RECORDS.md | 4 ++++ doc/dev/decisionrecords/APIGraphQLDesign.md | 26 +++++++++++++++++++++ doc/dev/decisionrecords/_TEMPLATE.md | 2 -- 3 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 doc/dev/decisionrecords/APIGraphQLDesign.md diff --git a/DEVELOPMENT_DECISION_RECORDS.md b/DEVELOPMENT_DECISION_RECORDS.md index 10b9e005809..ef0085f7171 100644 --- a/DEVELOPMENT_DECISION_RECORDS.md +++ b/DEVELOPMENT_DECISION_RECORDS.md @@ -104,3 +104,7 @@ Prefer immutable types over mutable. Use builders where appropriate. See [Avoid using records if you cannot encapsulate it properly](doc/dev/decisionrecords/RecordsPOJOsBuilders.md#records) +## GraphQL Best Practices - API Design + +[Follow best practices for designing GraphQL APIs. Our APIs are used by hundreds of clients +(web-pages/apps/services) and need to backwards compatible.](doc/dev/A) \ No newline at end of file diff --git a/doc/dev/decisionrecords/APIGraphQLDesign.md b/doc/dev/decisionrecords/APIGraphQLDesign.md new file mode 100644 index 00000000000..f739497c14c --- /dev/null +++ b/doc/dev/decisionrecords/APIGraphQLDesign.md @@ -0,0 +1,26 @@ +# GraphQL Best Practices - API Design + +Follow best practices for designing GraphQL APIs. Our APIs are used by hundreds of clients +(web-pages/apps/services) and need to be backwards compatible. A good reference used by several +of the OTP developers are the Production Ready GraphQL book by Marc-André Giroux. + + +## Pagination + +We use the [pagination](https://graphql.org/learn/pagination/) (a.k. Relay) specification for paging over entities like station, +stops, trips and routes. Very often OTP has a _final_ list of entities in memory. For non-entities +(Itinerary and Legs), witch does not always have an ID and is none trivial to reconstruct, it is +better to make a custom solution. + + +## Consistency + +Unfortunately, part of the GraphQL API is old and does not follow best practices. So, when adding +new features, consider what is best; To follow the existing style or follow the best practice. + + +### Context and Problem Statement + +Our APIs are used by hundreds of clients(web-pages/apps/services) and need to backwards compatible. +Correcting mistakes may not be possible or may take a long time. + diff --git a/doc/dev/decisionrecords/_TEMPLATE.md b/doc/dev/decisionrecords/_TEMPLATE.md index 45bb3b11d34..e184bdc6aaa 100644 --- a/doc/dev/decisionrecords/_TEMPLATE.md +++ b/doc/dev/decisionrecords/_TEMPLATE.md @@ -6,8 +6,6 @@ later. --> -Original pull-request: {#NNNN} - ### Context and Problem Statement From f431d1734a189bc69e66ffed2cb3569d56aed822 Mon Sep 17 00:00:00 2001 From: Thomas Gran Date: Thu, 24 Oct 2024 11:09:29 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Leonard Ehrenfried --- DEVELOPMENT_DECISION_RECORDS.md | 2 +- doc/dev/decisionrecords/APIGraphQLDesign.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/DEVELOPMENT_DECISION_RECORDS.md b/DEVELOPMENT_DECISION_RECORDS.md index ef0085f7171..f5923092a94 100644 --- a/DEVELOPMENT_DECISION_RECORDS.md +++ b/DEVELOPMENT_DECISION_RECORDS.md @@ -107,4 +107,4 @@ Prefer immutable types over mutable. Use builders where appropriate. See ## GraphQL Best Practices - API Design [Follow best practices for designing GraphQL APIs. Our APIs are used by hundreds of clients -(web-pages/apps/services) and need to backwards compatible.](doc/dev/A) \ No newline at end of file +(web-pages/apps/services) and need to be backwards compatible.](doc/dev/A) \ No newline at end of file diff --git a/doc/dev/decisionrecords/APIGraphQLDesign.md b/doc/dev/decisionrecords/APIGraphQLDesign.md index f739497c14c..c9546ddf6f3 100644 --- a/doc/dev/decisionrecords/APIGraphQLDesign.md +++ b/doc/dev/decisionrecords/APIGraphQLDesign.md @@ -7,9 +7,9 @@ of the OTP developers are the Production Ready GraphQL book by Marc-André Girou ## Pagination -We use the [pagination](https://graphql.org/learn/pagination/) (a.k. Relay) specification for paging over entities like station, -stops, trips and routes. Very often OTP has a _final_ list of entities in memory. For non-entities -(Itinerary and Legs), witch does not always have an ID and is none trivial to reconstruct, it is +We use the [pagination](https://graphql.org/learn/pagination/) (a.k. Relay) specification for paging over entities like stations, +stops, trips and routes. Very often OTP has a _finite_ list of entities in memory. For non-entities +(Itinerary and Legs), witch do not always have an ID and is none trivial to reconstruct, it is better to make a custom solution.