|
1 | 1 | :_content-type: ASSEMBLY |
2 | | - |
3 | | - |
4 | 2 | include::modules/attributes.adoc[] |
5 | | - |
6 | 3 | [id="api"] |
| 4 | += {productname} API guide |
7 | 5 |
|
8 | | -= {productname} API Guide |
| 6 | +The {productname} application programming interface (API) provides a comprehensive, RESTful interface for managing and automating tasks within {productname}. Designed around the link:https://oauth.net/2/[_OAuth 2.0 protocol_], this API enables secure, fine-grained access to {productname} resources, and allows administrators and users to perform such actions as creating repositories, managing images, setting permissions, and more. |
9 | 7 |
|
10 | | -The {productname} application programming interface (API) is an OAuth 2 RESTful API that consists of a set of endpoints for adding, displaying, changing and deleting features for {productname}. |
| 8 | +{productname} follows Semantic Versioning (SemVer) principles, ensuring predictable API stability across releases, such as: |
11 | 9 |
|
12 | | -{productname} abides by the link:https://semver.org/#summary[Semantic Versioning (SemVer) specifications]. The following conditions are met with each major, minor, and patch release: |
| 10 | +* *Major releases*: Introduce new capabilities. Might include breaking changes to API compatibility. For example, the API of {productname} _2.0_ differs from {productname} _3.0_. |
13 | 11 |
|
14 | | -* Major versions of {productname} might include incompatible API changes. For example, the API of {productname} 2.0 differs from {productname} 3.0. |
15 | | -* Minor versions of {productname}, for example, 3.y, adds functionality in a backwards compatible manner. |
16 | | -* Patch versions of {productname}, for example, 3.y.z, introduces backwards compatible bug fixes. |
| 12 | +* *Minor releases*: Add new functionality in a backward-compatible manner. For example, a _3.y_ release adds functionality to the version _3._ release. |
17 | 13 |
|
18 | | -Currently, {productname} uses the `api/v1` endpoint for 3.y.z releases. |
| 14 | +* *Patch releases*: Deliver bug fixes and improvements while preserving backward compatibility with minor releases, such as _3.y.z_. |
19 | 15 |
|
20 | | -This guide describes the `api/v1` endpoints and the browser-based examples for accessing those endpoints. |
| 16 | +The following guide describes the {productname} API in more detail, and provides details on the following topics: |
21 | 17 |
|
22 | | -include::modules/proc_use-api.adoc[leveloffset=+1] |
| 18 | +* OAuth 2 access tokens and how they compare to traditional API tokens and {productname}'s robot tokens |
| 19 | +* Generating an OAuth 2 access token |
| 20 | +* Best practices for token management |
| 21 | +* OAuth 2 access token capabilities |
| 22 | +* Using the {productname} API |
| 23 | +* {productname} API configuration examples |
23 | 24 |
|
| 25 | +This guide is accompanied with a second guide, . . ., that provides information about all `api/v1` endpoints and how to access those endpoints with example commands. |
24 | 26 |
|
| 27 | +include::modules/proc_use-api.adoc[leveloffset=+1] |
25 | 28 |
|
26 | 29 | == {productname} Application Programming Interface (API) |
27 | 30 | [id="ref-api-quay"] |
|
0 commit comments