Skip to content

Commit

Permalink
Some more doc link fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
lorenyu committed Dec 11, 2023
1 parent 0124364 commit 5cce9e5
Show file tree
Hide file tree
Showing 3 changed files with 8 additions and 28 deletions.
32 changes: 6 additions & 26 deletions docs/app/api-details.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,7 @@ See [Technical Overview](./technical-overview.md) for details on the technologie

Each endpoint is configured in the [openapi.generated.yml](/app/openapi.generated.yml) file which provides basic request validation. Each endpoint specifies an `operationId` that maps to a function defined in the code that will handle the request.

To make handling a request easier, an [ApiContext](/app/src/util/api_context.py) exists which will fetch the DB session, request body, and current user. This can be used like so:
```py
def example_post() -> flask.Response:
with api_context_manager() as api_context:
# Work with the request body
first_name = api_context.request_body["first_name"]

# Work with the user
current_user = api_context.current_user

# Work with the DB session
api_context.db_session.query(..)

# Return a response
return response_util.success_response(
message="Success",
data={"db_model_id": "1234"}, # Whatever the response object should be
status_code=201
)
```
For more complex usages, it is recommended you put the implementation into a separate handler file in order to keep the API entrypoints easier to read.

# Swagger
## Swagger

The Swagger UI can be reached locally at [http://localhost:8080/docs](http://localhost:8080/docs) when running the API. The UI is based on the [openapi.generated.yml](/app/openapi.generated.yml) file.
![Swagger UI](/docs/app/images/swagger-ui.png)
Expand All @@ -36,12 +14,14 @@ Each of the endpoints you've described in your openapi.generated.yml file will a

All model schemas defined can be found at the bottom of the UI.

# Routes
## Routes

## Health Check
[GET /v1/healthcheck](/app/src/route/healthcheck.py) is an endpoint for checking the health of the service. It verifies that the database is reachable, and that the API service itself is up and running.
### Health Check

[GET /v1/healthcheck](/app/src/api/healthcheck.py) is an endpoint for checking the health of the service. It verifies that the database is reachable, and that the API service itself is up and running.

Note this endpoint explicitly does not require authorization so it can be integrated with any automated monitoring you may build.

### Example Response

![Example Response](/docs/app/images/healthcheck-response.png)
2 changes: 1 addition & 1 deletion docs/app/database/database-access-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This document describes the best practices and patterns for how the application

## Client Initialization and Configuration

The database client is initialized when the application starts (see [src/\_\_main\_\_.py](../../../app/src/app.py). The database engine that is used to create acquire connections to the database is initialized using the database configuration defined in [postgres_config.py](app/src/adapters/db/clients/postgres_config.py), which is configured through environment variables. The initialized database client is then stored on the Flask app's [\`extensions\` dictionary](https://flask.palletsprojects.com/en/2.3.x/api/#flask.Flask.extensions) to be used throughout the lifetime of the application.
The database client is initialized when the application starts (see [src/\_\_main\_\_.py](../../../app/src/app.py). The database engine that is used to create acquire connections to the database is initialized using the database configuration defined in [postgres_config.py](/app/src/adapters/db/clients/postgres_config.py), which is configured through environment variables. The initialized database client is then stored on the Flask app's [\`extensions\` dictionary](https://flask.palletsprojects.com/en/2.3.x/api/#flask.Flask.extensions) to be used throughout the lifetime of the application.

## Session Management

Expand Down
2 changes: 1 addition & 1 deletion docs/infra/set-up-database.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Before creating migrations that create tables, first create a migration that inc
ALTER DEFAULT PRIVILEGES GRANT ALL ON TABLES TO app
```

This will cause all future tables created by the `migrator` user to automatically be accessible by the `app` user. See the [Postgres docs on ALTER DEFAULT PRIVILEGES](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html) for more info. As an example see the example app's migrations file [migrations.sql](/app/migrations.sql).
This will cause all future tables created by the `migrator` user to automatically be accessible by the `app` user. See the [Postgres docs on ALTER DEFAULT PRIVILEGES](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html) for more info. As an example see the example app's migrations file [migrations.sql](https://github.com/navapbc/template-infra/blob/main/app/migrations.sql).

Why is this needed? The reason is because the `migrator` role will be used by the migration task to run database migrations (creating tables, altering tables, etc.), while the `app` role will be used by the web service to access the database. Moreover, in Postgres, new tables won't automatically be accessible by roles other than the creator unless specifically granted, even if those other roles have usage access to the schema that the tables are created in. In other words if the `migrator` user created a new table `foo` in the `app` schema, the `app` user will not have automatically be able to access it by default.

Expand Down

0 comments on commit 5cce9e5

Please sign in to comment.