Add GraphQL pagination to Decision Records

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 be backwards compatible.](doc/dev/A) 

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 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. 
+
+
+## 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. 
+

doc/dev/decisionrecords/_TEMPLATE.md

@@ -6,8 +6,6 @@
   later. 
 -->
 
-Original pull-request: {#NNNN}
-
 
 ### Context and Problem Statement