X-Git-Url: https://git.cworth.org/git?p=lmno-api;a=blobdiff_plain;f=api.text;fp=api.text;h=0000000000000000000000000000000000000000;hp=42d4f0ee459dbecc99f313da8557fbf522f8a826;hb=90f657fbcb0291228454de58a43466ff569dea6b;hpb=e5e3acca67ae0e9118f77898b63f7d7c78c06e4e 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.