git.cworth.org Git - empires-api/blob - api.text

   1 Gameplay API endpoints (within a current game)
   2 ==============================================
   3 /events
   4
   5     This is a server-sent events stream that allows the server to push
   6     game-related events to clients. When a client connects to this API
   7     endpoint the server will return a header that includes:
   8
   9         Content-type: text/event-stream
  10         Connection: keep-alive
  11         Cache-Control: no-cache
  12
  13     and will keep the connection open to return events.
  14
  15     The following event types will be returned by the server:
  16
  17         TYPE: players
  18
  19         WHEN: When a client first connects
  20
  21         PURPOSE: Describes all players in the game already
  22
  23         EXAMPLE:
  24
  25                 event: players
  26                 data: [{"id":1,"name":"Carl"},{"id":2,"name":"Kevin"}]
  27
  28         TYPE: player-join
  29
  30         WHEN: When a player joins the game
  31
  32         EXAMPLE:
  33
  34                 event: player-join
  35                 data: {"id":3,"name":"Richard"}
  36
  37         TYPE: player-leave
  38
  39         WHEN: When a player leaves the game
  40
  41         EXAMPLE:
  42
  43                 event: player-leave
  44                 data: {"id":3}
  45
  46         TYPE: capture
  47
  48         WHEN: When one player captures another
  49
  50         EXAMPLE:
  51
  52                 event: capture
  53                 data: {"captor": 2, "captee": 1}
  54
  55 /register
  56
  57     Method: POST
  58
  59     Behavior: Adds a new player with "name" and "character" and assigns an id. Also will add a new empire with empty "captured" array
  60
  61     Example data: { "name": "Carl", "character: "Elvis" }
  62
  63 /deregister/<ID>
  64
  65     Method: POST
  66
  67     Behavior: Removes an existing player with the given ID
  68
  69 /reset
  70
  71     Method: POST
  72
  73     Behavior: Removes all players (bulk deregister)
  74
  75 /restart
  76
  77     Method: POST
  78
  79     Behavior: Eliminates all current empire ownership so the existing
  80     players can start a new game
  81
  82 /capture/<ID1>/<ID2>
  83
  84     Method: POST
  85
  86     Behavior: Indicate that empire ID1 has now captured ID2
  87
  88 /liberate/<ID>
  89
  90     Method: POST
  91
  92     Behavior: Indicate that empire ID is no longer captured (undoing a
  93     previous /capture)
  94
  95 /characters
  96
  97     Method: GET
  98
  99     Behavior: Returns a lists of all character names (in alphabetical order)
 100
 101     Example data: [ "Einstein", "Elvis", "Fred Flintstone" ]
 102
 103 /empires
 104
 105     Method: GET
 106
 107     Behavior: Shows which empires have been captured by other empires
 108
 109     Example data [ { "id": 1, "captures": [] },
 110                    { "id": 2, "captures": [1] },
 111                    { "id": 3, "captures": [4, 5, 6] },
 112                    { "id": 4, "captures": [2] },
 113                    { "id": 5, "captures": [] },
 114                    { "id": 6, "captures": [] } ]
 115
 116 /players
 117
 118     Method: GET
 119
 120     Behavior: Gets a list of all the player objects (without their
 121     character names)
 122
 123     Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ]
 124
 125 Server
 126 ======
 127 There's a sample server available at: https://families.cworth.org/api/
 128
 129 We plan to move this to https://empires.cworth.org at some point.