From 5e60dec6ec1b1677bd4906901896ba1de1e2520c Mon Sep 17 00:00:00 2001 From: Iris System Date: Mon, 27 Feb 2023 09:34:48 +1300 Subject: [PATCH] fix(api, docs): send HTTP 400 on empty User-Agent, update docs --- docs/content/api/errors.md | 3 ++- docs/content/api/reference.md | 7 +++++++ services/web-proxy/main.go | 4 +++- 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/content/api/errors.md b/docs/content/api/errors.md index b8419c0e..7fae4f6c 100644 --- a/docs/content/api/errors.md +++ b/docs/content/api/errors.md @@ -31,8 +31,9 @@ When something goes wrong, the API will send back a 4xx HTTP status code, along |code|HTTP response code|meaning| |---|---|---| |0|500|Internal server error, try again later| -|0|400|Bad Request (usually invalid JSON)| +|0|400|Invalid JSON, or invalid request format (check `error` key in the response body)| |0|401|Missing or invalid Authorization header| +|0|403|Your access to the API is blocked - please contact us in the support server| |20001|404|System not found.| |20002|404|Member not found.| |20003|404|Member '{memberRef}' not found.| diff --git a/docs/content/api/reference.md b/docs/content/api/reference.md index d233a9ac..f5ab10fa 100644 --- a/docs/content/api/reference.md +++ b/docs/content/api/reference.md @@ -21,7 +21,14 @@ For models that have them, the keys `id`, `uuid` and `created` are **not** user- Endpoints taking JSON bodies (eg. most `PATCH` and `PUT` endpoints) require the `Content-Type: application/json` header set. +## User agent + +The API requires the `User-Agent` header to be set to a non-empty string. Not doing so will return a `400 Bad Request` with a JSON body. + +If you are developing an application exposed to the public, we would appreciate if your `User-Agent` uniquely identifies your application, and (if possible) provides some contact information for the developers - so that we are able to contact you if we notice your application doing something it shouldn't. + ## Authentication + Authentication is done with a simple "system token". You can get your system token by running `pk;token` using the Discord bot, either in a channel with the bot or in DMs. Then, pass this token in the `Authorization` HTTP header on requests that require it. Failure to do so on endpoints that require authentication will return a `401 Unauthorized`. diff --git a/services/web-proxy/main.go b/services/web-proxy/main.go index 2ff9c74d..919dbc1b 100644 --- a/services/web-proxy/main.go +++ b/services/web-proxy/main.go @@ -50,7 +50,9 @@ type ProxyHandler struct{} func (p ProxyHandler) ServeHTTP(rw http.ResponseWriter, r *http.Request) { if r.Header.Get("User-Agent") == "" { // please set a valid user-agent - rw.WriteHeader(403) + rw.Header().Set("content-type", "application/json") + rw.WriteHeader(400) + rw.Write([]byte(`{"message":"A valid User-Agent header is required.","code":0}`)) return }