From 914fa3cf35d10ddd0cf99417b5b8e611d37c411a Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Fri, 31 May 2024 14:37:03 -0600 Subject: [PATCH 01/16] ApiDefinitionGuidelines: Add README section for API Definitions Signed-off-by: Gabe Goodhart --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ecfe2b6..b03af186 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The rules for merging depend on the type of change in question and its scope of ## Formatting Guidelines -Design documents should be placed in `docs/`. +Design documents should be placed in [docs/](./docs). API Specifications should be placed in [api-definitions/](./api-definitions). ### Text @@ -43,3 +43,7 @@ easily updated in the future as needed. Some options include: * [Mermaid](https://github.com/mermaid-js/mermaid#readme) * [Excalidraw](https://excalidraw.com/) ** Be sure to leave "Embed Scene" turned on when exporting the PNG. + +### API Specifications + +API definitions use [OpenAPI](https://www.openapis.org/) format in [yaml](https://yaml.org/). From 0181d0de69dcd4381dc964bec12a94cb88519dc7 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Fri, 31 May 2024 14:53:25 -0600 Subject: [PATCH 02/16] ApiDefinitionGuidelines: Add stub of api-definitions directory Signed-off-by: Gabe Goodhart --- api-definitions/README.md | 17 +++++++++++++++++ api-definitions/instructlab.yaml | 6 ++++++ api-definitions/platform.yaml | 6 ++++++ 3 files changed, 29 insertions(+) create mode 100644 api-definitions/README.md create mode 100644 api-definitions/instructlab.yaml create mode 100644 api-definitions/platform.yaml diff --git a/api-definitions/README.md b/api-definitions/README.md new file mode 100644 index 00000000..4c9913d0 --- /dev/null +++ b/api-definitions/README.md @@ -0,0 +1,17 @@ +# API Definitions + +The common abstract interface for the service APIs is defined by [REST APIs](https://www.redhat.com/en/topics/api/what-is-a-rest-api) using [OpenAPI](https://www.openapis.org/). This project is the central home for these API definitions. + +## Style Guidelines + +* Use `kebab-case` for path elements +* Use `snake_case` for properties +* Use `UpperCamelCase` for internal reusable schema names + +## API Layout + +* There are two main portions of the APIs: + * [instructlab.yaml](./instructlab.yaml): This defines the user-facing `InstructLab` REST API + * [platform.yaml](./platform.yaml): This defines the platform-level APIs used by the `InstructLab` workflow. +* Each platform `Capability` should own its own fully-functional sub-API file that can be used by individual capability service implementations +* Any schema object that is reused between endpoints should be housed in a schema file under [common](./common) diff --git a/api-definitions/instructlab.yaml b/api-definitions/instructlab.yaml new file mode 100644 index 00000000..096ea0e5 --- /dev/null +++ b/api-definitions/instructlab.yaml @@ -0,0 +1,6 @@ +openapi: '3.0.2' +info: + title: InstructLab + version: '0.1.0' +# TODO +paths: {} diff --git a/api-definitions/platform.yaml b/api-definitions/platform.yaml new file mode 100644 index 00000000..4f69e7f0 --- /dev/null +++ b/api-definitions/platform.yaml @@ -0,0 +1,6 @@ +openapi: '3.0.2' +info: + title: AI Platform (We need a name for the IL-agnostic platform!) + version: '0.1.0' +# TODO +paths: {} From b02d87a082b2e9c34ed3d1727dd036141978a027 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Fri, 31 May 2024 14:54:38 -0600 Subject: [PATCH 03/16] ApiDefinitionGuidelines: Add api-definitions-guidelines doc Signed-off-by: Gabe Goodhart --- docs/api-definitions-guidelines.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/api-definitions-guidelines.md diff --git a/docs/api-definitions-guidelines.md b/docs/api-definitions-guidelines.md new file mode 100644 index 00000000..af8ecf7c --- /dev/null +++ b/docs/api-definitions-guidelines.md @@ -0,0 +1,20 @@ +# API Definitions Guidelines + +This document describes how service APIs will be managed for `InstructLab` and the sub-components of the `InstructLab` backend. + +## What parts of InstructLab need service APIs? + +There are two primary classes of service APIs needed to support InstructLab: + +* `Platform APIs`: These are APIs that are ignorant of `InstructLab` and provide generic AI platform capabilities (e.g., Fine Tuning, SDG, Eval) +* `InstructLab APIs`: These are the APIs that reflect the user-facing functionality of `InstructLab` itself. They are aware of the end-to-end `InstructLab` workflow. + +The `InstructLab APIs` are essential for hosting `InstructLab` as a service in a repeatable way. The `Platform APIs` are critical for component reuse and extensibility (e.g., new SDG algorithms for new taxonomy data types), but they are not strictly required for hosting `InstructLab` as a service. + +## How will service APIs be defined? + +Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [yaml](https://yaml.org/). For structural and style guidelines, see [api-definitions](../api-definitions/README.md). + +## Where will service API definitions live? + +Service API definitions will live in [api-definitions](../api-definitions) within this repo. \ No newline at end of file From 88256c081b315357730ed4990dcdb96880fce405 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Fri, 31 May 2024 15:12:22 -0600 Subject: [PATCH 04/16] ApiDefinitionGuidelines: Fix spellcheck errors API and 'extensibilitiy' should be in the dictionary, but yaml -> YAML is reasonable. Signed-off-by: Gabe Goodhart --- .spellcheck-en-custom.txt | 4 ++++ README.md | 2 +- docs/api-definitions-guidelines.md | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index 22db77fb..bb9ae6f0 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -3,6 +3,8 @@ Abhishek Akash AMDGPU +API +api arge arXiv backend @@ -37,6 +39,7 @@ Eval Excalidraw exfiltrate exfiltrating +extensibility Finetuning formedness GFX @@ -135,3 +138,4 @@ XT XTX Xu YAML +yaml \ No newline at end of file diff --git a/README.md b/README.md index b03af186..f998a2a1 100644 --- a/README.md +++ b/README.md @@ -46,4 +46,4 @@ easily updated in the future as needed. Some options include: ### API Specifications -API definitions use [OpenAPI](https://www.openapis.org/) format in [yaml](https://yaml.org/). +API definitions use [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). diff --git a/docs/api-definitions-guidelines.md b/docs/api-definitions-guidelines.md index af8ecf7c..0dae2825 100644 --- a/docs/api-definitions-guidelines.md +++ b/docs/api-definitions-guidelines.md @@ -13,7 +13,7 @@ The `InstructLab APIs` are essential for hosting `InstructLab` as a service in a ## How will service APIs be defined? -Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [yaml](https://yaml.org/). For structural and style guidelines, see [api-definitions](../api-definitions/README.md). +Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). For structural and style guidelines, see [api-definitions](../api-definitions/README.md). ## Where will service API definitions live? From dee4d6073ef82859fa3dc1e26199c5e705bbd23c Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 4 Jun 2024 14:04:49 -0600 Subject: [PATCH 05/16] ApiDefinitionGuidelines: Add section on API versioning Signed-off-by: Gabe Goodhart --- .spellcheck-en-custom.txt | 1 + api-definitions/README.md | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index bb9ae6f0..a6e9fae2 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -4,6 +4,7 @@ Abhishek Akash AMDGPU API +API's api arge arXiv diff --git a/api-definitions/README.md b/api-definitions/README.md index 4c9913d0..aa9eb5f6 100644 --- a/api-definitions/README.md +++ b/api-definitions/README.md @@ -15,3 +15,9 @@ The common abstract interface for the service APIs is defined by [REST APIs](htt * [platform.yaml](./platform.yaml): This defines the platform-level APIs used by the `InstructLab` workflow. * Each platform `Capability` should own its own fully-functional sub-API file that can be used by individual capability service implementations * Any schema object that is reused between endpoints should be housed in a schema file under [common](./common) + +## Versioning and Stability + +**WARNING** At this stage in development, we make no guarantees about stability and support for APIs! + +**FUTURE**: Once stabilized, the APIs will follow an agreed-upon form of [semantic versioning](https://semver.org/) so that users can rely on the API's stability. The decision of how to version the API and at what granularity to do so is still under discussion. \ No newline at end of file From f32fbc59a31e7afac6231532687162ffcd8e5adb Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Thu, 6 Jun 2024 14:11:33 -0600 Subject: [PATCH 06/16] ApiDefinitionGuidelines: Move API definitions under docs/backend Signed-off-by: Gabe Goodhart --- docs/{ => backend}/api-definitions-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/{ => backend}/api-definitions-guidelines.md (86%) diff --git a/docs/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md similarity index 86% rename from docs/api-definitions-guidelines.md rename to docs/backend/api-definitions-guidelines.md index 0dae2825..b78c1685 100644 --- a/docs/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -13,8 +13,8 @@ The `InstructLab APIs` are essential for hosting `InstructLab` as a service in a ## How will service APIs be defined? -Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). For structural and style guidelines, see [api-definitions](../api-definitions/README.md). +Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). For structural and style guidelines, see [api-definitions](../../api-definitions/README.md). ## Where will service API definitions live? -Service API definitions will live in [api-definitions](../api-definitions) within this repo. \ No newline at end of file +Service API definitions will live in [api-definitions](../../api-definitions) within this repo. \ No newline at end of file From 570697c44657561aded6a023fc81786f213321e3 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Fri, 7 Jun 2024 07:24:23 -0600 Subject: [PATCH 07/16] ApiDefinitionGuidelines: Expand on the casing guidelines Signed-off-by: Gabe Goodhart --- .spellcheck-en-custom.txt | 2 ++ api-definitions/README.md | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index a6e9fae2..fa143d40 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -8,6 +8,7 @@ API's api arge arXiv +ascii backend backends benchmarking @@ -127,6 +128,7 @@ triager's triagers unquantized USM +utf UX venv watsonx diff --git a/api-definitions/README.md b/api-definitions/README.md index aa9eb5f6..9b857ecc 100644 --- a/api-definitions/README.md +++ b/api-definitions/README.md @@ -5,8 +5,15 @@ The common abstract interface for the service APIs is defined by [REST APIs](htt ## Style Guidelines * Use `kebab-case` for path elements + * All characters must be in the [ascii](https://www.ascii-code.com/) character set to avoid percent encoding in URIs + * All letters must be lowercase + * Words are separated by the `-` (dash) character * Use `snake_case` for properties + * All characters must be in the [utf-8](https://www.w3schools.com/charsets/ref_html_utf8.asp) character set for simple `json` encoding + * Words are separated by the `_` (underscore) character * Use `UpperCamelCase` for internal reusable schema names + * These are internal names, so the character set is not limited + * Words are capitalized and concatenated with no separator ## API Layout From 18cdcf14bac97b2f0c553a1aa3b55b3b88eac668 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Mon, 10 Jun 2024 12:22:11 -0600 Subject: [PATCH 08/16] ApiDefinitionGuidelines: Adjust proposal to place API specs in a new repo Signed-off-by: Gabe Goodhart --- .spellcheck-en-custom.txt | 2 ++ api-definitions/README.md | 30 ---------------- api-definitions/instructlab.yaml | 6 ---- api-definitions/platform.yaml | 6 ---- docs/backend/api-definitions-guidelines.md | 40 +++++++++++++++++++++- 5 files changed, 41 insertions(+), 43 deletions(-) delete mode 100644 api-definitions/README.md delete mode 100644 api-definitions/instructlab.yaml delete mode 100644 api-definitions/platform.yaml diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index fa143d40..a944e0a8 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -114,7 +114,9 @@ Shivchander Signoff Srivastava subdirectory +submodule Sudalairaj +sync'ed Taj tatsu TBD diff --git a/api-definitions/README.md b/api-definitions/README.md deleted file mode 100644 index 9b857ecc..00000000 --- a/api-definitions/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# API Definitions - -The common abstract interface for the service APIs is defined by [REST APIs](https://www.redhat.com/en/topics/api/what-is-a-rest-api) using [OpenAPI](https://www.openapis.org/). This project is the central home for these API definitions. - -## Style Guidelines - -* Use `kebab-case` for path elements - * All characters must be in the [ascii](https://www.ascii-code.com/) character set to avoid percent encoding in URIs - * All letters must be lowercase - * Words are separated by the `-` (dash) character -* Use `snake_case` for properties - * All characters must be in the [utf-8](https://www.w3schools.com/charsets/ref_html_utf8.asp) character set for simple `json` encoding - * Words are separated by the `_` (underscore) character -* Use `UpperCamelCase` for internal reusable schema names - * These are internal names, so the character set is not limited - * Words are capitalized and concatenated with no separator - -## API Layout - -* There are two main portions of the APIs: - * [instructlab.yaml](./instructlab.yaml): This defines the user-facing `InstructLab` REST API - * [platform.yaml](./platform.yaml): This defines the platform-level APIs used by the `InstructLab` workflow. -* Each platform `Capability` should own its own fully-functional sub-API file that can be used by individual capability service implementations -* Any schema object that is reused between endpoints should be housed in a schema file under [common](./common) - -## Versioning and Stability - -**WARNING** At this stage in development, we make no guarantees about stability and support for APIs! - -**FUTURE**: Once stabilized, the APIs will follow an agreed-upon form of [semantic versioning](https://semver.org/) so that users can rely on the API's stability. The decision of how to version the API and at what granularity to do so is still under discussion. \ No newline at end of file diff --git a/api-definitions/instructlab.yaml b/api-definitions/instructlab.yaml deleted file mode 100644 index 096ea0e5..00000000 --- a/api-definitions/instructlab.yaml +++ /dev/null @@ -1,6 +0,0 @@ -openapi: '3.0.2' -info: - title: InstructLab - version: '0.1.0' -# TODO -paths: {} diff --git a/api-definitions/platform.yaml b/api-definitions/platform.yaml deleted file mode 100644 index 4f69e7f0..00000000 --- a/api-definitions/platform.yaml +++ /dev/null @@ -1,6 +0,0 @@ -openapi: '3.0.2' -info: - title: AI Platform (We need a name for the IL-agnostic platform!) - version: '0.1.0' -# TODO -paths: {} diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index b78c1685..bb783e6b 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -17,4 +17,42 @@ Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format i ## Where will service API definitions live? -Service API definitions will live in [api-definitions](../../api-definitions) within this repo. \ No newline at end of file +Service API definitions will live a new repository github.com/instructlab/service-api-definitions. This repo will have two primary responsibilities: + +1. House the static service API definitions +2. Build and publish any language-specific generated packages for consumption by service implementation projects (see below) + +## How will service implementations reference shared APIs? + +When a project chooses to implement one or more service APIs, there are three acceptable methods for doing so, listed in order of preference: + +1. Consume a supported language-specific package. The `service-api-definitions` repo will build consumable packages with generated code for supported languages. This is the preferred method of consumption as it avoids repository references and code duplication. +2. For languages without a supported package, the `service-api-definitions` repo may be held as a [git submodule](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules). +3. It is also acceptable for an implementation to copy the relevant API definitions to the local project repository. Any changes made in the central repository will need to be sync'ed by the project owners, and any new APIs added in the project will not be considered usable until they have been integrated into the central API definitions. + +## Style Guidelines + +* Use `kebab-case` for path elements + * All characters must be in the [ascii](https://www.ascii-code.com/) character set to avoid percent encoding in URIs + * All letters must be lowercase + * Words are separated by the `-` (dash) character +* Use `snake_case` for properties + * All characters must be in the [utf-8](https://www.w3schools.com/charsets/ref_html_utf8.asp) character set for simple `json` encoding + * Words are separated by the `_` (underscore) character +* Use `UpperCamelCase` for internal reusable schema names + * These are internal names, so the character set is not limited + * Words are capitalized and concatenated with no separator + +## API Layout + +* There will be two main portions of the APIs: + * `instructlab.yaml`: This defines the user-facing `InstructLab` REST API + * `platform.yaml`: This defines the platform-level APIs used by the `InstructLab` workflow. +* Each platform `Capability` should own its own fully-functional sub-API file that can be used by individual capability service implementations +* Any schema object that is reused between endpoints should be housed in a schema file under the central `common` directory. + +## Versioning and Stability + +**WARNING** At this stage in development, we make no guarantees about stability and support for APIs! + +**FUTURE**: Once stabilized, the APIs will follow an agreed-upon form of [semantic versioning](https://semver.org/) so that users can rely on the API's stability. The decision of how to version the API and at what granularity to do so is still under discussion. \ No newline at end of file From 02b5a19778b052a0d4027da55e58a02c690ae13e Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 11 Jun 2024 11:35:43 -0600 Subject: [PATCH 09/16] Improvements in language for OpenAPI Co-authored-by: Martin Hickey Signed-off-by: Gabe Goodhart --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f998a2a1..2c3cae9f 100644 --- a/README.md +++ b/README.md @@ -46,4 +46,4 @@ easily updated in the future as needed. Some options include: ### API Specifications -API definitions use [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). +API definitions use the [OpenAPI Specification](https://www.openapis.org/) (OAS) written in [YAML](https://yaml.org/). From 20fb26e0fd2dd12f5b44afbebef54892ac975d0c Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 11 Jun 2024 11:37:01 -0600 Subject: [PATCH 10/16] ApiDefinitionGuidelines: Remove mention of api-definitions in this repo Signed-off-by: Gabe Goodhart --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2c3cae9f..e4d47673 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The rules for merging depend on the type of change in question and its scope of ## Formatting Guidelines -Design documents should be placed in [docs/](./docs). API Specifications should be placed in [api-definitions/](./api-definitions). +Design documents should be placed in [docs/](./docs). ### Text From aba535bf5e7ea4ebf7071d16bead5dbd59061385 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 11 Jun 2024 11:41:16 -0600 Subject: [PATCH 11/16] ApiDefinitionGuidelines: Remove reference to local api-definitions dir Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index bb783e6b..5d4d69e7 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -13,7 +13,7 @@ The `InstructLab APIs` are essential for hosting `InstructLab` as a service in a ## How will service APIs be defined? -Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). For structural and style guidelines, see [api-definitions](../../api-definitions/README.md). +Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). ## Where will service API definitions live? From f67ffff34a2da74526c955c37949fdbdd46eddfc Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Wed, 12 Jun 2024 10:26:30 -0600 Subject: [PATCH 12/16] ApiDefinitionGuidelines: update service-api-definitions -> openapi for repo name Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index 5d4d69e7..266bbff5 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -17,7 +17,7 @@ Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format i ## Where will service API definitions live? -Service API definitions will live a new repository github.com/instructlab/service-api-definitions. This repo will have two primary responsibilities: +Service API definitions will live a new repository github.com/instructlab/openapi. This repo will have two primary responsibilities: 1. House the static service API definitions 2. Build and publish any language-specific generated packages for consumption by service implementation projects (see below) @@ -26,9 +26,9 @@ Service API definitions will live a new repository github.com/instructlab/servic When a project chooses to implement one or more service APIs, there are three acceptable methods for doing so, listed in order of preference: -1. Consume a supported language-specific package. The `service-api-definitions` repo will build consumable packages with generated code for supported languages. This is the preferred method of consumption as it avoids repository references and code duplication. -2. For languages without a supported package, the `service-api-definitions` repo may be held as a [git submodule](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules). 3. It is also acceptable for an implementation to copy the relevant API definitions to the local project repository. Any changes made in the central repository will need to be sync'ed by the project owners, and any new APIs added in the project will not be considered usable until they have been integrated into the central API definitions. +1. Consume a supported language-specific package. The `openapi` repo will build/publish/tag consumable packages with generated code for supported languages based on standard package distribution channels for the given language. This is the preferred method of consumption as it avoids repository references and code duplication. +2. For languages without a supported package, the `openapi` repo may be held as a [git submodule](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules). ## Style Guidelines From a90d70bffe7261b4142490f1890832c891ce27ec Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Wed, 12 Jun 2024 10:26:56 -0600 Subject: [PATCH 13/16] ApiDefinitionGuidelines: Remove third option for consuming APIs by copy Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index 266bbff5..ac9e4e99 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -26,7 +26,6 @@ Service API definitions will live a new repository github.com/instructlab/openap When a project chooses to implement one or more service APIs, there are three acceptable methods for doing so, listed in order of preference: -3. It is also acceptable for an implementation to copy the relevant API definitions to the local project repository. Any changes made in the central repository will need to be sync'ed by the project owners, and any new APIs added in the project will not be considered usable until they have been integrated into the central API definitions. 1. Consume a supported language-specific package. The `openapi` repo will build/publish/tag consumable packages with generated code for supported languages based on standard package distribution channels for the given language. This is the preferred method of consumption as it avoids repository references and code duplication. 2. For languages without a supported package, the `openapi` repo may be held as a [git submodule](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules). From e4867158056cc28389cd8810a360a685408d41b3 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Mon, 24 Jun 2024 09:47:52 -0600 Subject: [PATCH 14/16] Update docs/backend/api-definitions-guidelines.md Phrasing change for `openai` repo Co-authored-by: Nathan Weinberg <31703736+nathan-weinberg@users.noreply.github.com> Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index ac9e4e99..642d885a 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -17,7 +17,7 @@ Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format i ## Where will service API definitions live? -Service API definitions will live a new repository github.com/instructlab/openapi. This repo will have two primary responsibilities: +Service API definitions will live a new repository: `instructlab/openapi`. This repo will have two primary responsibilities: 1. House the static service API definitions 2. Build and publish any language-specific generated packages for consumption by service implementation projects (see below) From 12ae3a08ae94bbfc3e6aaaba0460c4a394fe1d3d Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 2 Jul 2024 11:07:29 -0600 Subject: [PATCH 15/16] Typo fix in api definitions guidelines Co-authored-by: Martin Hickey Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index 642d885a..99cb0ebd 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -17,7 +17,7 @@ Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format i ## Where will service API definitions live? -Service API definitions will live a new repository: `instructlab/openapi`. This repo will have two primary responsibilities: +Service API definitions will live in a new repository: `instructlab/openapi`. This repo will have two primary responsibilities: 1. House the static service API definitions 2. Build and publish any language-specific generated packages for consumption by service implementation projects (see below) From 5aff3e222d1e722208d1813500d191b655ed6970 Mon Sep 17 00:00:00 2001 From: Gabe Goodhart Date: Tue, 2 Jul 2024 11:10:47 -0600 Subject: [PATCH 16/16] Wording improvements from review Co-authored-by: Martin Hickey Signed-off-by: Gabe Goodhart --- docs/backend/api-definitions-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/backend/api-definitions-guidelines.md b/docs/backend/api-definitions-guidelines.md index 99cb0ebd..f083f81a 100644 --- a/docs/backend/api-definitions-guidelines.md +++ b/docs/backend/api-definitions-guidelines.md @@ -13,7 +13,7 @@ The `InstructLab APIs` are essential for hosting `InstructLab` as a service in a ## How will service APIs be defined? -Service APIs will be defined using [OpenAPI](https://www.openapis.org/) format in [YAML](https://yaml.org/). +Service APIs will be defined using the [OpenAPI Specification (OAS)](https://www.openapis.org/) written in [YAML](https://yaml.org/). ## Where will service API definitions live? @@ -24,7 +24,7 @@ Service API definitions will live in a new repository: `instructlab/openapi`. Th ## How will service implementations reference shared APIs? -When a project chooses to implement one or more service APIs, there are three acceptable methods for doing so, listed in order of preference: +When a project chooses to implement one or more service APIs, there are two acceptable methods for doing so, listed in order of preference: 1. Consume a supported language-specific package. The `openapi` repo will build/publish/tag consumable packages with generated code for supported languages based on standard package distribution channels for the given language. This is the preferred method of consumption as it avoids repository references and code duplication. 2. For languages without a supported package, the `openapi` repo may be held as a [git submodule](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules).