-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
40 changed files
with
2,907 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,3 +3,4 @@ __pycache__ | |
.env | ||
dist/ | ||
.python-version | ||
.pytest_cache |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
# TDP Server | ||
|
||
`tdp-server` provides a server to interact with [`tdp-lib`](https://github.com/tOSIT-IO/tdp-lib). | ||
|
||
## Requirements | ||
|
||
The server is made with Python. The following is required: | ||
|
||
- [Python](https://www.python.org/) `3.9.5` | ||
- [Poetry](https://python-poetry.org/) `1.7.1` | ||
|
||
## Installation | ||
|
||
Install the `tdp-server` dependencies in the pyproject.toml as follows: | ||
|
||
```bash | ||
poetry install | ||
``` | ||
|
||
## Usage | ||
|
||
To see the specification: | ||
|
||
```sh | ||
# Launch the server | ||
poetry run uvicorn tdp_server.main:app --reload | ||
``` | ||
|
||
Specification is available at <http://localhost:8000/docs>. | ||
|
||
## Discussion | ||
|
||
- Endpoint prefix `/api/v1` as base path has been chosen. | ||
|
||
[Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#urls) recommends directly starting it from `/`, however the [Ambari server](https://github.com/apache/ambari/blob/trunk/ambari-server/docs/api/v1/components.md) choses this endpoint prefix and it explicits what the user is using. Moreover the [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html) states that the version must be specified. | ||
|
||
- For versioning `v1` has been chosen for first version. | ||
|
||
`v1` has been chosen like in the Ambari server, the [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html) give an example with the version `v1`, however, the [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#116) state that we must chose semantic versioning. | ||
|
||
- All resources are pluralized except `plan`. | ||
|
||
Since all resources consist of several items (configurations, services, components, deployments), the resource name is in plural form as stated as a must requirement in the [Zalando API guideline](https://opensource.zalando.com/restful-api-guidelines/#134) and in the [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html). Only the `\plan` resource is singular since there is only one plan before it can be deployed and also to be consistent with TDP lib. | ||
|
||
- All resource names are written in lower-case. | ||
|
||
As stated in the [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html) all resource names must be written in lower-case. | ||
|
||
- Query parmeters in URL are written using snake_case. | ||
|
||
The [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html) recommend using snake_case or camelcase for query parameters, however in the [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/query-params/) snake_case is used and it is also the way to declare variables in python. Query parameters whch are used as path parameters in the URL are therefore also in snake_case although they shouldn't be according to the first document but is performed in the FastAPI documentation. | ||
|
||
- Kebab-case will be used for path segments except query parameters. | ||
|
||
For now, no resource name or action is a combination of two words. However, if it is the case, kebab-case must be used as stated in the [Naming Conventions of the Australian government API](https://api.gov.au/sections/naming-conventions.html) and the [Zalando API guideline](https://opensource.zalando.com/restful-api-guidelines/#129). | ||
|
||
- Verbs have been chosen where actions are done. | ||
|
||
The [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#urls) state that it MUST be verb-free and the same is mentioned in the[dreamfactory blog](https://blog.dreamfactory.com/best-practices-for-naming-rest-api-endpoints/). The reason is that with the path we should access ressources and the actions are defined with the GET, PUT, POST, PATCH, DELETE methods. However, we are not using a REST API and with `/plan` we perform different actions such as `resume` or `reconfigure` with the same post method and both actions are not performed on different resources so introducing a verb is the best way of description. For the `deploy` endpoint the question is more debatable, however the clearest wording is favored and therefore we chose to maintain the verb. | ||
|
||
- No empty path segments and trailing slashes. | ||
|
||
The [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#136) state that the URL must not have any empty path segments or trailing slashes. The [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/query-params/) give an example where there is a trailing slash, however to be as clean as possible and avoid any confusion no trailing slash occurs in any URL. | ||
|
||
- Used domain specific resource names. | ||
|
||
Each resource name is domain specific which represent either the elements in TDP (`/services` and `/components`) or actions in TDP Manager as stated as a must requirement in the [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#142). | ||
|
||
- Resources and sub-resources are identified via path segments. | ||
|
||
The `components` resource is a sub-resource of `services` which is a sub-resource of `configurations`. The path segment for a component looks the following `/api/v1/configurations/services/{service_id}/components/{component_id}`. This has been chosen to improve consumer experience while following the setup of TDP. The [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#143) state this practice as a must requirement. | ||
|
||
- Cursor-based pagination instead of offset-based has been chosen. | ||
|
||
This is stated as a SHOULD requirement in the [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#pagination). | ||
|
||
- JSON is used as response body. | ||
|
||
The JSON format is used as response body of every endpoint so that each function returns a JSON object as stated as a must requirement in the [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#167). Schemas are written using the Pydantic BaseModel which will read the body as JSON. The [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/body/) shows this method to declare request bodies. | ||
|
||
- Enum values are declared as UPPER_CASE. | ||
|
||
As recommended by the [Zalando API guidelines](https://opensource.zalando.com/restful-api-guidelines/#240) enum values should be written as UPPER_SNAKE_CASE. |
Oops, something went wrong.