Reformat to remove table

Author: JPrevost

docs/architecture-decisions/0006-use-graphql-for-api.md

@@ -12,14 +12,53 @@ Supercedes [4. Use OpenAPI Specification](0004-use-openapi-specification.md)
 
 The initial TIMDEX implementation chose a REST API. During development of new expanded features, we revisted this decision and looked at our options and needs.
 
-### Options considered
-
-|   | GraphQL  | OpenAPI spec REST API  |  JSON API |
-|---|---|---|---|
-| Description | GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. | The OpenAPI Specification is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services | JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability. |
-| Pros |  <ul><li>GraphiQL interactive editor allows users to explore the API without writing any code</li><li>Users can request the exact data they want as part of the query</li><li>Schema allows users and applications to import and understand data types</li></ul>| <ul><li>REST APIs are comfortable for many developers as they have used them before</li><li>uses OpenAPI spec and transitioning to V2 in OpenAPI would be familiar</li></ul>  | <ul><li>Adds standardization to REST APIs</li></ul> |
-| Neutral | | <ul><li>v2 requires significant changes to v1 and is essentially a rewrite so any apps using v1 will need to make changes regardless of if we keep this similar spec</li><li>Auto generation of documentation is useful, but does not meet all of our documentation plans for v2</li></ul> |
-| Cons | <ul><li>Requires developers to learn GraphQL syntax</li><li>More difficult to scale with simple caching</li></ul> | <ul><li>Requires many decisions to be made as to how to request data when designing the spec</li><li>The only way to know how to use the API will be to rely on our spec and our documentation. It will be a unique API</li></ul>  | <ul><li>Unclear how well adopted it is</li></ul> |
+### Options Considered
+
+#### GraphQL
+
+**Description:** GraphQL is a query language for APIs...
+
+**Pros:**
+
+- GraphiQL interactive editor allows users to explore the API without writing any code
+- Users can request the exact data they want as part of the query
+- Schema allows users and applications to import and understand data types
+
+**Cons:**
+
+- Requires developers to learn GraphQL syntax
+- More difficult to scale with simple caching
+
+#### OpenAPI spec REST API
+
+**Description:** The OpenAPI Specification is a specification...
+
+**Pros:**
+
+- REST APIs are comfortable for many developers as they have used them before
+- uses OpenAPI spec and transitioning to V2 in OpenAPI would be familiar
+
+**Neutral:**
+
+- v2 requires significant changes to v1 and is essentially a rewrite so any apps using v1 will need to make changes regardless of if we keep this similar spec
+- Auto generation of documentation is useful, but does not meet all of our documentation plans for v2
+
+**Cons:**
+
+- Requires many decisions to be made as to how to request data when designing the spec
+- The only way to know how to use the API will be to rely on our spec and our documentation
+
+#### JSON API
+
+**Description:** JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.
+
+**Pros:**
+
+- Adds standardization to REST APIs
+
+**Cons:**
+
+- Unclear how well adopted it is
 
 ## Decision