From 9f12eef10e756bc6bbf8280ca8f09d454b7e27df Mon Sep 17 00:00:00 2001 From: Evan Sosenko Date: Thu, 27 Jun 2024 20:07:27 +0000 Subject: [PATCH] docs: Add description to README (#8) * docs: Add description to README * Add motivation * ci: Format code * Update README.md * Update README.md * ci: Format code * Update README.md Co-authored-by: Andrii Balitskyi <84702959+andrii-balitskyi@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Andrii Balitskyi <84702959+andrii-balitskyi@users.noreply.github.com> --------- Co-authored-by: Seam Bot Co-authored-by: Andrii Balitskyi <84702959+andrii-balitskyi@users.noreply.github.com> --- README.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74be9ce..4c759b7 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,40 @@ Build tools for the Seam API using this blueprint. ## Description -TODO +A blueprint is a simplified description of an API schema that is optimized for code and documentation generation. + +The blueprint schema assumes the API follows Seam API design guidelines, +and will evolve with those guidelines and any SDK, documentation, or product quality requirements. + +The blueprint defines the following core concepts: + +- Endpoint: a path that accepts an HTTP request and returns a response. +- Route: the direct parent path of a collection of one or more endpoints. +- Subroute: a route that is nested under another route. +- Namespace: the direct parent path of a collection routes only: there are no endpoints under this path. +- Resource: every endpoint that returns non-empty data returns a resource or a collection of resources. ## Motivation -TODO +The scope of the [OpenAPI Specification](https://swagger.io/specification/) covers arbitrarily complicated APIs, +while the Seam API follows very predictable and simplified API design patterns. + +For this reason, Seam has encountered several challenges working directly with the OpenAPI Specification: + +- Existing tools built on the OpenAPI Specification cannot meet Seam's requirements or require non-trivial extensions. +- Extending the OpenAPI Specification with non-standard properties to support Seam's SDK and documentation requirements + is not directly compatible with existing tools. +- Seam's requirements and scope are overall simpler than the broad use-cases existing tools based on the OpenAPI Specification are trying to solve. +- All existing Seam tooling must first expend duplicated effort parsing and flattening the OpenAPI Specification into a form more natural to the Seam API. +- This creates a high barrier of entry for working with the Seam API specification + as one must first deeply understand how to parse the OpenAPI Specification for any practical application. + +The blueprint addresses these concerns: + +- The blueprint module centralizes on a source of truth for parsing the OpenAPI Specification into something usable. +- The blueprint schema matches naturally to the Seam API design and is immediately usable for practical application. +- The blueprint is not limited by the OpenAPI Specification or constrained by the wide scope of supporting any API. + It is optimized for Seam's requirements and can evolve faster to meet Seam's specific concerns and integrate directly with other Seam integrated tooling. ## Installation