From 9383bbb9d353142fa319d5513e96027a6ef3434e Mon Sep 17 00:00:00 2001 From: github-actions Date: Mon, 16 Dec 2024 16:03:32 +0000 Subject: [PATCH] Update REST API documentation Mon Dec 16 16:03:32 UTC 2024 --- docs/restapi.json | 734 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 734 insertions(+) create mode 100644 docs/restapi.json diff --git a/docs/restapi.json b/docs/restapi.json new file mode 100644 index 0000000..3820f89 --- /dev/null +++ b/docs/restapi.json @@ -0,0 +1,734 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "My API Documentation", + "description": "This is the OpenAPI documentation for My API.", + "contact": { + "email": "support@phplist.com" + }, + "license": { + "name": "AGPL-3.0-or-later", + "url": "https://www.gnu.org/licenses/agpl.txt" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://www.phplist.com/api/v2", + "description": "Production server" + } + ], + "paths": { + "/lists": { + "get": { + "tags": [ + "lists" + ], + "summary": "Gets a list of all subscriber lists.", + "description": "Returns a JSON list of all subscriber lists.", + "operationId": "81c74c22179cb7ac081aa6e77b9f6631", + "parameters": [ + { + "name": "session", + "in": "header", + "description": "Session ID obtained from authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "properties": { + "name": { + "type": "string", + "example": "News" + }, + "description": { + "type": "string", + "example": "News (and some fun stuff)" + }, + "creation_date": { + "type": "string", + "format": "date-time", + "example": "2016-06-22T15:01:17+00:00" + }, + "list_position": { + "type": "integer", + "example": 12 + }, + "subject_prefix": { + "type": "string", + "example": "phpList" + }, + "public": { + "type": "boolean", + "example": true + }, + "category": { + "type": "string", + "example": "news" + }, + "id": { + "type": "integer", + "example": 1 + } + }, + "type": "object" + } + } + } + } + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/lists/{list}": { + "get": { + "tags": [ + "lists" + ], + "summary": "Gets a subscriber list.", + "description": "Returns a single subscriber list with specified ID.", + "operationId": "0dc1b40be222c4283ef1e39ee210d077", + "parameters": [ + { + "name": "list", + "in": "path", + "description": "List ID", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "session", + "in": "header", + "description": "Session ID obtained from authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object" + }, + "example": { + "name": "News", + "description": "News (and some fun stuff)", + "creation_date": "2016-06-22T15:01:17+00:00", + "list_position": 12, + "subject_prefix": "phpList", + "public": true, + "category": "news", + "id": 1 + } + } + } + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + }, + "404": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "There is no list with that ID." + } + }, + "type": "object" + } + } + } + } + } + }, + "delete": { + "tags": [ + "lists" + ], + "summary": "Deletes a list.", + "description": "Deletes a single subscriber list.", + "operationId": "ab4b8e42dd519312a942be1f3a86771b", + "parameters": [ + { + "name": "session", + "in": "header", + "description": "Session ID", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "list", + "in": "path", + "description": "List ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success" + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided." + } + }, + "type": "object" + } + } + } + }, + "404": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "There is no session with that ID." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/lists/{list}/members": { + "get": { + "tags": [ + "lists" + ], + "summary": "Gets a list of all subscribers (members) of a subscriber list.", + "description": "Returns a JSON list of all subscribers for a subscriber list.", + "operationId": "29f6848c27ee3e30b7e4bd7997c73a18", + "parameters": [ + { + "name": "session", + "in": "header", + "description": "Session ID obtained from authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "list", + "in": "path", + "description": "List ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "properties": { + "creation_date": { + "type": "string", + "format": "date-time", + "example": "2016-07-22T15:01:17+00:00" + }, + "email": { + "type": "string", + "example": "oliver@example.com" + }, + "confirmed": { + "type": "boolean", + "example": true + }, + "blacklisted": { + "type": "boolean", + "example": true + }, + "bounce_count": { + "type": "integer", + "example": 17 + }, + "unique_id": { + "type": "string", + "example": "95feb7fe7e06e6c11ca8d0c48cb46e89" + }, + "html_email": { + "type": "boolean", + "example": true + }, + "disabled": { + "type": "boolean", + "example": true + }, + "id": { + "type": "integer", + "example": 1 + } + }, + "type": "object" + } + } + } + } + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/lists/{list}/count": { + "get": { + "tags": [ + "lists" + ], + "summary": "Gets the total number of subscribers of a list", + "description": "Returns a count of all subscribers in a given list.", + "operationId": "c1e2f17c0078014a816c914a25d8e889", + "parameters": [ + { + "name": "session", + "in": "header", + "description": "Session ID obtained from authentication", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "list", + "in": "path", + "description": "List ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success" + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/sessions": { + "post": { + "tags": [ + "sessions" + ], + "summary": "Log in or create new session.", + "description": "Given valid login data, this will generate a login token that will be valid for 1 hour.", + "operationId": "08336f63605d853592fc942e7c13fcd7", + "requestBody": { + "description": "Pass session credentials", + "required": true, + "content": { + "application/json": { + "schema": { + "required": [ + "login_name", + "password" + ], + "properties": { + "login_name": { + "type": "string", + "format": "string", + "example": "admin" + }, + "password": { + "type": "string", + "format": "password", + "example": "eetIc/Gropvoc1" + } + }, + "type": "object" + } + } + } + }, + "responses": { + "201": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "properties": { + "id": { + "type": "integer", + "example": 1234 + }, + "key": { + "type": "string", + "example": "2cfe100561473c6cdd99c9e2f26fa974" + }, + "expiry": { + "type": "string", + "example": "2017-07-20T18:22:48+00:00" + } + }, + "type": "object" + } + } + } + }, + "400": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "Empty json, invalid data and or incomplete data" + } + }, + "type": "object" + } + } + } + }, + "401": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "Not authorized." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/sessions/{session}": { + "delete": { + "tags": [ + "sessions" + ], + "summary": "Delete a session.", + "description": "Delete the session passed as a parameter.", + "operationId": "fbeec6cb2db5898313a8dd3a91b2b57a", + "parameters": [ + { + "name": "session", + "in": "path", + "description": "Session ID", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success" + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + }, + "404": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "There is no session with that ID." + } + }, + "type": "object" + } + } + } + } + } + } + }, + "/subscriber": { + "post": { + "tags": [ + "subscribers" + ], + "summary": "Create a subscriber", + "description": "Creates a new subscriber (if there is no subscriber with the given email address yet).", + "operationId": "9dc1ae0a66e2eed292c4aed09bab8de0", + "parameters": [ + { + "name": "session", + "in": "header", + "description": "Session ID obtained from authentication", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Pass session credentials", + "required": true, + "content": { + "application/json": { + "schema": { + "required": [ + "email" + ], + "properties": { + "email": { + "type": "string", + "format": "string", + "example": "admin@example.com" + }, + "confirmed": { + "type": "boolean", + "example": false + }, + "blacklisted": { + "type": "boolean", + "example": false + }, + "html_email": { + "type": "boolean", + "example": false + }, + "disabled": { + "type": "boolean", + "example": false + } + }, + "type": "object" + } + } + } + }, + "responses": { + "201": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "properties": { + "creation_date": { + "type": "string", + "format": "date-time", + "example": "2017-12-16T18:44:27+00:00" + }, + "email": { + "type": "string", + "example": "subscriber@example.com" + }, + "confirmed": { + "type": "boolean", + "example": false + }, + "blacklisted": { + "type": "boolean", + "example": false + }, + "bounced": { + "type": "integer", + "example": 0 + }, + "unique_id": { + "type": "string", + "example": "69f4e92cf50eafca9627f35704f030f4" + }, + "html_email": { + "type": "boolean", + "example": false + }, + "disabled": { + "type": "boolean", + "example": false + }, + "id": { + "type": "integer", + "example": 1 + } + }, + "type": "object" + } + } + } + }, + "403": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "No valid session key was provided as basic auth password." + } + }, + "type": "object" + } + } + } + }, + "409": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "This resource already exists." + } + }, + "type": "object" + } + } + } + }, + "422": { + "description": "Failure", + "content": { + "application/json": { + "schema": { + "properties": { + "message": { + "type": "string", + "example": "Some fields invalid: email, confirmed, html_email" + } + }, + "type": "object" + } + } + } + } + } + } + } + }, + "tags": [ + { + "name": "lists", + "description": "lists" + }, + { + "name": "sessions", + "description": "sessions" + }, + { + "name": "subscribers", + "description": "subscribers" + } + ] +} \ No newline at end of file