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.

Sign up for GitHub

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

Jump to bottom

HTTP API to offer OpenAPI document #510

Closed
orpheuslummis opened this issue Jun 9, 2022 · 0 comments · Fixed by #1960
Closed

HTTP API to offer OpenAPI document #510

orpheuslummis opened this issue Jun 9, 2022 · 0 comments · Fixed by #1960
Assignees
@nasdf
Labels
area/api Related to the external API component
Milestone
DefraDB v0.8

Comments

@orpheuslummis
Copy link
Contributor

This issue recommends for DefraDB's HTTP API to offer an OpenAPI document. OpenAPI is a "standard interface description language for HTTP APIs". (A potential decision following this PR might be not to do it).

For reference see https://www.openapis.org/ and https://spec.openapis.org/oas/v3.1.0

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Potential benefits of using OpenAPI:

  • Generating standard-looking documentation and online playground
  • Machine readability and discovery of API
  • Extensive community tooling can be used https://openapi.tools/ such as data validators, security analysis, SDK generators, etc
  • Integration with cloud platforms such as https://cloud.google.com/endpoints/docs/openapi to help "secure, monitor, analyze, and set quotas
  • ...

Notes on DefraDB HTTP API-specific implementation:
@orpheuslummis orpheuslummis added the area/api Related to the external API component label Jun 9, 2022
@orpheuslummis orpheuslummis mentioned this issue Apr 3, 2023
Closed
@orpheuslummis orpheuslummis mentioned this issue Apr 30, 2023
Open
@orpheuslummis orpheuslummis mentioned this issue May 9, 2023
Closed
@nasdf nasdf self-assigned this Jul 14, 2023
@nasdf nasdf added this to the DefraDB v0.6 milestone Jul 14, 2023
@fredcarle fredcarle modified the milestones: DefraDB v0.6, DefraDB v0.7 Jul 22, 2023
@jsimnz jsimnz removed this from the DefraDB v0.7 milestone Sep 18, 2023
@nasdf nasdf mentioned this issue Oct 11, 2023
Merged
4 tasks
nasdf added a commit that referenced this issue Oct 18, 2023
@nasdf
feat: Add OpenAPI route (#1960)
28f207d 
## Relevant issue(s)

Resolves #510 

## Description

This PR adds an HTTP endpoint that returns an OpenAPI specification for
DefraDB. The definitions are part code generation and part hand written.
This should work well for adding examples and more documentation in the
future.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

## How has this been tested?

View endpoint in browser `localhost:9181/api/v0/openapi`.

Double checked with OpenAPI validator tool.

Specify the platform(s) on which this was tested:
- MacOS
nasdf added a commit to nasdf/defradb that referenced this issue Oct 18, 2023
@nasdf
feat: Add OpenAPI route (sourcenetwork#1960)
c923848 
Resolves sourcenetwork#510

This PR adds an HTTP endpoint that returns an OpenAPI specification for
DefraDB. The definitions are part code generation and part hand written.
This should work well for adding examples and more documentation in the
future.

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

View endpoint in browser `localhost:9181/api/v0/openapi`.

Double checked with OpenAPI validator tool.

Specify the platform(s) on which this was tested:
- MacOS
@fredcarle fredcarle added this to the DefraDB v0.8 milestone Nov 6, 2023
shahzadlone pushed a commit to shahzadlone/defradb that referenced this issue Feb 23, 2024
@nasdf
feat: Add OpenAPI route (sourcenetwork#1960)
2481499 
## Relevant issue(s)

Resolves sourcenetwork#510 

## Description

This PR adds an HTTP endpoint that returns an OpenAPI specification for
DefraDB. The definitions are part code generation and part hand written.
This should work well for adding examples and more documentation in the
future.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

## How has this been tested?

View endpoint in browser `localhost:9181/api/v0/openapi`.

Double checked with OpenAPI validator tool.

Specify the platform(s) on which this was tested:
- MacOS
@shahzadlone shahzadlone mentioned this issue Jun 4, 2024
Merged
shahzadlone added a commit that referenced this issue Jun 4, 2024
@shahzadlone
docs: Add http/openapi documentation & ci workflow (#2678)
7dc07e7 
## Relevant issue(s)
Related #510 
Resolve #2677

## Description
- Detect OpenAPI / HTTP documentation is always up to date.
- Generate open-api docs in the appropriate dir.

## How has this been tested?
- using `act` tool
- manually introducing a change and seeing the action fail:
https://github.com/sourcenetwork/defradb/actions/runs/9359749777/job/25763961265?pr=2678

Specify the platform(s) on which this was tested:
- WSL2 instance
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@nasdf nasdf

Labels
area/api Related to the external API component
Projects
None yet
Milestone
DefraDB v0.8
Development

Successfully merging a pull request may close this issue.

feat: Add OpenAPI route nasdf/defradb
4 participants
@orpheuslummis @nasdf @jsimnz @fredcarle