Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Api definition guidelines #71

Closed
Closed
Changes from 11 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
914fa3c
ApiDefinitionGuidelines: Add README section for API Definitions
gabe-l-hart May 31, 2024
0181d0d
ApiDefinitionGuidelines: Add stub of api-definitions directory
gabe-l-hart May 31, 2024
b02d87a
ApiDefinitionGuidelines: Add api-definitions-guidelines doc
gabe-l-hart May 31, 2024
88256c0
ApiDefinitionGuidelines: Fix spellcheck errors
gabe-l-hart May 31, 2024
dee4d60
ApiDefinitionGuidelines: Add section on API versioning
gabe-l-hart Jun 4, 2024
f32fbc5
ApiDefinitionGuidelines: Move API definitions under docs/backend
gabe-l-hart Jun 6, 2024
570697c
ApiDefinitionGuidelines: Expand on the casing guidelines
gabe-l-hart Jun 7, 2024
18cdcf1
ApiDefinitionGuidelines: Adjust proposal to place API specs in a new …
gabe-l-hart Jun 10, 2024
02b5a19
Improvements in language for OpenAPI
gabe-l-hart Jun 11, 2024
20fb26e
ApiDefinitionGuidelines: Remove mention of api-definitions in this repo
gabe-l-hart Jun 11, 2024
aba535b
ApiDefinitionGuidelines: Remove reference to local api-definitions dir
gabe-l-hart Jun 11, 2024
f67ffff
ApiDefinitionGuidelines: update service-api-definitions -> openapi fo…
gabe-l-hart Jun 12, 2024
a90d70b
ApiDefinitionGuidelines: Remove third option for consuming APIs by copy
gabe-l-hart Jun 12, 2024
e486715
Update docs/backend/api-definitions-guidelines.md
gabe-l-hart Jun 24, 2024
39579d0
Merge branch 'main' into ApiDefinitionGuidelines
hickeyma Jul 2, 2024
12ae3a0
Typo fix in api definitions guidelines
gabe-l-hart Jul 2, 2024
5aff3e2
Wording improvements from review
gabe-l-hart Jul 2, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .spellcheck-en-custom.txt
Original file line number Diff line number Diff line change
@@ -3,8 +3,12 @@
Abhishek
Akash
AMDGPU
API
API's
api
arge
arXiv
ascii
backend
backends
benchmarking
@@ -37,6 +41,7 @@ Eval
Excalidraw
exfiltrate
exfiltrating
extensibility
Finetuning
formedness
GFX
@@ -109,7 +114,9 @@ Shivchander
Signoff
Srivastava
subdirectory
submodule
Sudalairaj
sync'ed
Taj
tatsu
TBD
@@ -123,6 +130,7 @@ triager's
triagers
unquantized
USM
utf
UX
venv
watsonx
@@ -135,3 +143,4 @@ XT
XTX
Xu
YAML
yaml
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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).

### 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 the [OpenAPI Specification](https://www.openapis.org/) (OAS) written in [YAML](https://yaml.org/).
58 changes: 58 additions & 0 deletions docs/backend/api-definitions-guidelines.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# 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/).

## 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 `instructlab/service-api-definitions`. This repo will have two primary responsibilities:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer specification over definitions

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hickeyma, can you elaborate on that preference in light of the definition vs specification article? My thought is that this new repo would explicitly house definitions (for machine consumption). Are you thinking that it would also house specifications (for human consumption)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to weigh in, the Kubernetes community often uses "spec" to define the API specification. I've seen "model" being used elsewhere. I'm ok with both TBH.

Copy link
Author

@gabe-l-hart gabe-l-hart Jun 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, good point. I think you're right that the kubernetes community uses spec in this context a lot. I do think it's also a little muddy with CustomResourceDefinition which is the thing that defines the schema for a "thing" and then spec being the canonical name for the field within that schema where a user would create an instance of that "thing." I that vein, it still feels like Definition is the consistent word where the schema is defined.

That said, I'm a big fan of putting a Cares About number (1-10) on this kind of opinion and then just taking the highest one.

CA: 2

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we went with instructlab/openai. I'm fine with that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Service API definitions will live a new repository github.com/instructlab/service-api-definitions. This repo will have two primary responsibilities:
Service API specifications will live a new repository `instructlab/service-api-specification`. This repo will have two primary responsibilities:

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same question as above. Why the preference for specification vs definition if the explicit goal of the repo is to own machine-consumable definitions. Are you thinking that the yaml format is the human-readable specification vs the generated language-specific packages are the machine-readable definitions?


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.