From: Carl Worth Date: Sat, 23 May 2020 18:27:01 +0000 (-0700) Subject: Rename api.txt to empires.txt X-Git-Url: https://git.cworth.org/git?p=empires-api;a=commitdiff_plain;h=90f657fbcb0291228454de58a43466ff569dea6b Rename api.txt to empires.txt Since the API documented in this file is only for the lower-level Empires-game specific API, (which sits below the LMNO API documented in lmno.txt). --- diff --git a/api.text b/api.text deleted file mode 100644 index 42d4f0e..0000000 --- a/api.text +++ /dev/null @@ -1,193 +0,0 @@ -Empires Game Protocol -===================== -Version: 0.6 - -For a specific game the following API endpoints are defined. -(Note: Only the trailing portion of the API URI is provided here. - The preceding portions of the path must be determined externally.) - -/events - - This is a server-sent events stream that allows the server to push - game-related events to clients. When a client connects to this API - endpoint the server will return a header that includes: - - Content-type: text/event-stream - Connection: keep-alive - Cache-Control: no-cache - - and will keep the connection open to return events. - - The following event types will be returned by the server: - - TYPE: players - - WHEN: When a client first connects - - PURPOSE: Describes all players in the game already - - EXAMPLE: - - event: players - data: [{"id":1,"name":"Carl"},{"id":2,"name":"Kevin"}] - - TYPE: player-join - - WHEN: When a player joins the game - - EXAMPLE: - - event: player-join - data: {"id":3,"name":"Richard"} - - TYPE: player-leave - - WHEN: When a player leaves the game - - EXAMPLE: - - event: player-leave - data: {"id":3} - - TYPE: game-state - - WHEN: When client first connects and whenever game state changes - - VALUES: Event gives both the old and new state. - Each will be one of the following: - - none: Pseudo-state used as old_state when game is started - join: Players are choosing characters and joining the game - reveal: Character names are being revealed to players - capture: Players are guessing characters in capture attempts - - NOTE: When a client first connects, it may see multiple - game-state transitions, to transition step-by-step from - the initial state to the state of the current game. See - the example below which would be presented to a client - joining a game that is already in the "reveal state. - - EXAMPLES: - - event: game-state - data: {"old_state":"none","new_state":"join"} - - event: game-state - data: {"old_state":"join","new_state":"reveal"} - - TYPE: character-reveal - - WHEN: Periodically during the "reveal" state of the game - - EXAMPLE: - - event: character-reveal - data: {"character":"Albert Einstein"} - - TYPE: capture - - WHEN: When one player captures another - - EXAMPLE: - - event: capture - data: {"captor": 2, "captee": 1} - -/register - - Method: POST - - Behavior: Adds a new player with "name" and "character" and - assigns an id. Also will add a new empire with empty "captured" - array. - - Note: If the client supports cookies and has previously set a - nickname in the current session via the upper-level /profile API, - then the name can be omitted from the data here and the profile - nickname will be used instead. - - Example data: { "name": "Carl", "character: "Elvis" } - -/deregister/ - - Method: POST - - Behavior: Removes an existing player with the given ID - -/reveal - - Method: POST - - When: Only valid when in game state of JOIN - - Behavior: Change state to REVEAL; reveal character names to all clienta - -/start - - Method: POST - - When: Only valid when in game state of REVEAL - - Behavior: Change game state to CAPTURE - -/reset - - Method: POST - - Behavior: Removes all players (bulk deregister) - -/restart - - Method: POST - - Behavior: Eliminates all current empire ownership so the existing - players can start a new game - -/capture// - - Method: POST - - Behavior: Indicate that empire ID1 has now captured ID2 - -/liberate/ - - Method: POST - - Behavior: Indicate that empire ID is no longer captured (undoing a - previous /capture) - -/characters - - Method: GET - - Behavior: Returns a lists of all character names (in alphabetical order) - - Example data: [ "Einstein", "Elvis", "Fred Flintstone" ] - -/empires - - Method: GET - - Behavior: Shows which empires have been captured by other empires - - Example data [ { "id": 1, "captures": [] }, - { "id": 2, "captures": [1] }, - { "id": 3, "captures": [4, 5, 6] }, - { "id": 4, "captures": [2] }, - { "id": 5, "captures": [] }, - { "id": 6, "captures": [] } ] - -/players - - Method: GET - - Behavior: Gets a list of all the player objects (without their - character names) - - Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ] - -Server -====== -There's a sample server available at: https://families.cworth.org/api/ - -We plan to move this to https://empires.cworth.org at some point. diff --git a/empires.txt b/empires.txt new file mode 100644 index 0000000..42d4f0e --- /dev/null +++ b/empires.txt @@ -0,0 +1,193 @@ +Empires Game Protocol +===================== +Version: 0.6 + +For a specific game the following API endpoints are defined. +(Note: Only the trailing portion of the API URI is provided here. + The preceding portions of the path must be determined externally.) + +/events + + This is a server-sent events stream that allows the server to push + game-related events to clients. When a client connects to this API + endpoint the server will return a header that includes: + + Content-type: text/event-stream + Connection: keep-alive + Cache-Control: no-cache + + and will keep the connection open to return events. + + The following event types will be returned by the server: + + TYPE: players + + WHEN: When a client first connects + + PURPOSE: Describes all players in the game already + + EXAMPLE: + + event: players + data: [{"id":1,"name":"Carl"},{"id":2,"name":"Kevin"}] + + TYPE: player-join + + WHEN: When a player joins the game + + EXAMPLE: + + event: player-join + data: {"id":3,"name":"Richard"} + + TYPE: player-leave + + WHEN: When a player leaves the game + + EXAMPLE: + + event: player-leave + data: {"id":3} + + TYPE: game-state + + WHEN: When client first connects and whenever game state changes + + VALUES: Event gives both the old and new state. + Each will be one of the following: + + none: Pseudo-state used as old_state when game is started + join: Players are choosing characters and joining the game + reveal: Character names are being revealed to players + capture: Players are guessing characters in capture attempts + + NOTE: When a client first connects, it may see multiple + game-state transitions, to transition step-by-step from + the initial state to the state of the current game. See + the example below which would be presented to a client + joining a game that is already in the "reveal state. + + EXAMPLES: + + event: game-state + data: {"old_state":"none","new_state":"join"} + + event: game-state + data: {"old_state":"join","new_state":"reveal"} + + TYPE: character-reveal + + WHEN: Periodically during the "reveal" state of the game + + EXAMPLE: + + event: character-reveal + data: {"character":"Albert Einstein"} + + TYPE: capture + + WHEN: When one player captures another + + EXAMPLE: + + event: capture + data: {"captor": 2, "captee": 1} + +/register + + Method: POST + + Behavior: Adds a new player with "name" and "character" and + assigns an id. Also will add a new empire with empty "captured" + array. + + Note: If the client supports cookies and has previously set a + nickname in the current session via the upper-level /profile API, + then the name can be omitted from the data here and the profile + nickname will be used instead. + + Example data: { "name": "Carl", "character: "Elvis" } + +/deregister/ + + Method: POST + + Behavior: Removes an existing player with the given ID + +/reveal + + Method: POST + + When: Only valid when in game state of JOIN + + Behavior: Change state to REVEAL; reveal character names to all clienta + +/start + + Method: POST + + When: Only valid when in game state of REVEAL + + Behavior: Change game state to CAPTURE + +/reset + + Method: POST + + Behavior: Removes all players (bulk deregister) + +/restart + + Method: POST + + Behavior: Eliminates all current empire ownership so the existing + players can start a new game + +/capture// + + Method: POST + + Behavior: Indicate that empire ID1 has now captured ID2 + +/liberate/ + + Method: POST + + Behavior: Indicate that empire ID is no longer captured (undoing a + previous /capture) + +/characters + + Method: GET + + Behavior: Returns a lists of all character names (in alphabetical order) + + Example data: [ "Einstein", "Elvis", "Fred Flintstone" ] + +/empires + + Method: GET + + Behavior: Shows which empires have been captured by other empires + + Example data [ { "id": 1, "captures": [] }, + { "id": 2, "captures": [1] }, + { "id": 3, "captures": [4, 5, 6] }, + { "id": 4, "captures": [2] }, + { "id": 5, "captures": [] }, + { "id": 6, "captures": [] } ] + +/players + + Method: GET + + Behavior: Gets a list of all the player objects (without their + character names) + + Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ] + +Server +====== +There's a sample server available at: https://families.cworth.org/api/ + +We plan to move this to https://empires.cworth.org at some point.