diff options
| -rw-r--r-- | doc/api.md | 82 |
1 files changed, 40 insertions, 42 deletions
diff --git a/doc/api.md b/doc/api.md index 37e3e2937..b731c7e32 100644 --- a/doc/api.md +++ b/doc/api.md @@ -7,11 +7,10 @@ - [Compatibility](#compatibility) - [Unless stated otherwise ...](#unless-stated-otherwise-) - [Access levels](#access-levels) -- [General response structure](#general-response-structure) - - [Error handling](#error-handling) -- [General errors](#general-errors) - [Endpoints](#endpoints) - [Examples](#examples) +- [Error handling](#error-handling) + - [General errors](#general-errors) The API provides programmatic access to upload, delete files, view the currently uploaded ones and combine them to multipastes, as well as functions @@ -67,45 +66,6 @@ the table include those above themselves. | apikey | Allows to delete uploads and view the history | | full | Allows everything | -## General response structure - -Replies will always contain a `status` field which can contain the following -values: `success`, `error`. If the reply does not contain the status field -it should be regarded as invalid. - -If `status=success` the reply will contain a `data` field which contains -function specific data. - -### Error handling - -If `status=error` the reply will be of the following format: - -```javascript -// Error response format -responseError = { - "status": "error", - "message": "A message that can be displayed to the user", - "error_id": "program/useable/error/id", - "data": object or array, // optional, only used if mentioned -} -``` - - -## General errors - -These are the most common errors that can be returned by any API call. - -| error_id | Message | Note | -| -------- | ------- | ---- | -| api/invalid-version | Invalid API version requested | Failed syntax check | -| api/invalid-endpoint | Invalid endpoint requested | Failed syntax check | -| api/version-not-supported | Requested API version is not supported | | -| api/unknown-endpoint | Unknown endpoint requested | Likely a typo in your URL | -| internal-error | An unhandled internal server error occured | | -| user/api-login-failed | API key login failed | | -| api/insufficient-permissions | Access denied: Access level too low | | -| api/not-authenticated | Not authenticated | Likely no apikey was sent | - ## Endpoints Documentation for specific endpoints can be found in `./doc/api/`: @@ -113,6 +73,14 @@ Documentation for specific endpoints can be found in `./doc/api/`: * [Documentation for the /file/ endpoints](api/file.md) * [Documentation for the /user/ endpoints](api/user.md) +Responses will always contain a `status` field which can contain the following +values: `success`, `error`. If the response does not contain the status field +it should be regarded as invalid. + +If `status=success` the response will contain a `data` field which contains +function specific data. + + ```javascript // General definitions @@ -143,3 +111,33 @@ your shell history and in top/ps if used. Be careful on untrusted systems. apikey="anApiKey" base="https://paste.xinu.at/api/v2.0.0" ``` + +## Error handling + +If `status=error` the response will be of the following format: + +```javascript +// Error response format +responseError = { + "status": "error", + "message": "A message that can be displayed to the user", + "error_id": "program/useable/error/id", + "data": object or array, // optional, only used if mentioned +} +``` + + +### General errors + +These are the most common errors that can be returned by any API call. + +| error_id | Message | Note | +| -------- | ------- | ---- | +| api/invalid-version | Invalid API version requested | Failed syntax check | +| api/invalid-endpoint | Invalid endpoint requested | Failed syntax check | +| api/version-not-supported | Requested API version is not supported | | +| api/unknown-endpoint | Unknown endpoint requested | Likely a typo in your URL | +| internal-error | An unhandled internal server error occured | | +| user/api-login-failed | API key login failed | | +| api/insufficient-permissions | Access denied: Access level too low | | +| api/not-authenticated | Not authenticated | Likely no apikey was sent | |