diff --git a/README.md b/README.md index 690016a..437e4db 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,31 @@ returns the user's profile information. No personal data is stored. ## PESUAuth LIVE Deployment - You can access the PESUAuth API endpoints [here](https://pesu-auth.onrender.com/). -- You can view the health status of the API on the [PESUAuth Health Dashboard](https://xzlk85cp.status.cron-job.org/). +- You can view the health status of the API on the health check pages for + [production](https://xzlk85cp.status.cron-job.org) and [staging](https://6ns95sgb.status.cron-job.org). +- You can view detailed metrics and KPIs for both environments on the + [PESUAuth metrics dashboard](https://loyalplateau1250.grafana.net/public-dashboards/bd1df85e9420490f88978906b0d9fbdf), + built from the counters that [`/metrics`](#metrics) exposes. #### API Status -![Cron job status](https://api.cron-job.org/jobs/4424640/69701a6f8df1d307/status-7.svg)\ -![Cron job status](https://api.cron-job.org/jobs/6338038/9feb0f217be714ec/status-7.svg)\ -![Cron job status](https://api.cron-job.org/jobs/5672615/1d744f1dc18fb505/status-7.svg)\ -![Cron job status](https://api.cron-job.org/jobs/4424663/d5a30351867acec9/status-7.svg) +| **Environment** | **Check** | **Status** | +| --------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Production | Docs | ![Docs](https://api.cron-job.org/jobs/4424640/69701a6f8df1d307/status-7.svg) | +| Production | Health | ![Health](https://api.cron-job.org/jobs/6338038/9feb0f217be714ec/status-7.svg) | +| Production | Authentication | ![Authentication](https://api.cron-job.org/jobs/5672615/1d744f1dc18fb505/status-7.svg) | +| Production | Authentication with Profile Data | ![Authentication with profile](https://api.cron-job.org/jobs/4424663/d5a30351867acec9/status-7.svg) | +| Staging | Docs | ![Docs](https://api.cron-job.org/jobs/6382167/bc84078c3b85999c/status-7.svg) | +| Staging | Health | ![Health](https://api.cron-job.org/jobs/6382168/e38759ed59c0d9c1/status-7.svg) | +| Staging | Authentication | ![Authentication](https://api.cron-job.org/jobs/6382175/226ee5764400bf01/status-7.svg) | +| Staging | Authentication with Profile Data | ![Authentication with profile](https://api.cron-job.org/jobs/6382173/5cff341ab10ab962/status-7.svg) | +| | Detailed metrics and KPIs | [![Grafana](https://img.shields.io/badge/Grafana-metrics%20%26%20KPIs-F46800?logo=grafana&logoColor=white)](https://loyalplateau1250.grafana.net/public-dashboards/bd1df85e9420490f88978906b0d9fbdf) | > [!NOTE] > All timestamps are in UTC. > [!WARNING] -> The live version is hosted on a free tier server located in the United States. As a result, you *might* experience higher latencies and slower response times, compared to running the API locally or on a server closer to your location. +> Both environments are hosted on free tier servers located in Singapore. As a result, you *might* experience higher latencies and slower response times, compared to running the API locally or on a server closer to your location. ## How to run PESUAuth locally @@ -119,6 +130,19 @@ object, with the user's profile information if requested. | `profile` | Yes | `boolean` | `False` | Whether to fetch profile information | | `fields` | Yes | `list[str]` | `None` | Which fields to fetch from the profile information. If not provided, all fields will be fetched | +#### Responses + +| **Code** | **When** | +| -------- | --------------------------------------------------------------------------------- | +| `200` | The credentials are valid. `profile` is included if it was requested | +| `400` | The request body failed validation — a missing field, or an unknown profile field | +| `401` | Invalid username or password, or the user does not exist | +| `422` | PESU Academy's profile page could not be parsed, which means their page changed | +| `500` | An unexpected failure, rendered by the catch-all handler | +| `502` | PESU Academy could not be reached, or did not answer with what was expected | + +Every non-`200` carries the same `{status, message, timestamp}` body, with `status` set to `false`. + #### Response Object On authentication, it returns the following parameters in a JSON object. If the authentication was successful and @@ -153,6 +177,8 @@ If the authentication fails, this field will not be present in the response. ### `/health` +Answers `200` whenever the process is serving; a `500` would come from the catch-all handler, as on any other endpoint. + This endpoint can be used to check the health of the API. It's useful for monitoring and uptime checks. This endpoint does not take any request parameters. @@ -609,7 +635,7 @@ scrape_configs: ### `/readme` -This endpoint redirects to the project's official GitHub repository. This endpoint does not take any request parameters. +This endpoint redirects to the project's official GitHub repository with a `308`, and takes no request parameters. A `500` would come from the catch-all handler, as on any other endpoint. ### Integrating your application with the PESUAuth API @@ -651,7 +677,7 @@ print(response.json()) "campus": "RR" }, "message": "Login successful.", - "timestamp": "2024-07-28 22:30:10.103368+05:30" + "timestamp": "2024-07-28T22:30:10.103368+05:30" } ``` @@ -668,13 +694,13 @@ curl -X POST http://localhost:5000/authenticate \ }' ``` -#### Response +##### Response ```json { "status": true, "message": "Login successful.", - "timestamp": "2024-07-28 22:30:10.103368+05:30" + "timestamp": "2024-07-28T22:30:10.103368+05:30" } ``` diff --git a/pyproject.toml b/pyproject.toml index 01a8f69..ff63373 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pesu-auth" -version = "4.4.0" +version = "4.5.0" description = "A simple API to authenticate PESU credentials using PESU Academy." readme = "README.md" requires-python = ">=3.14" diff --git a/uv.lock b/uv.lock index 8c62995..e33e842 100644 --- a/uv.lock +++ b/uv.lock @@ -630,7 +630,7 @@ wheels = [ [[package]] name = "pesu-auth" -version = "4.4.0" +version = "4.5.0" source = { editable = "." } dependencies = [ { name = "fastapi" },