game API docs

There are four API calls you can make:

/api/claim (POST)
/api/player (POST)
/api/score (GET)
/api/token (GET)

Authentication is required for everything but an initial claim and score retreival. Players create an account with their first valid claim. Players get a bearer token to identify their account in response to their first valid claim. The bearer token must be provided as an HTTP Authorization header for any future requrest that requires authorization.

Examples

How do I prove I won a challenge?

If it's your first win, you can do this:

curl "https://angstloch.io/api/claim" -H "accept: application/json" -H "Content-Type: application/json" -d '{"gameId":"someGameId","winCode":"00000000-0000-4000-8000-000000000000","playerId":"JohnDoe"}'

You'll get back a JSON blob with a bearer token. Keep that and use it in the future. Please don't just create a bunch of accounts.

Additional wins are recorded like this:

curl "https://angstloch.io/api/claim" -H "accept: application/json" -H "Authorization: Bearer 00000000-0000-4000-8000-000000000000" -H "Content-Type: application/json" -d '{"gameId":"someGameId","winCode":"00000000-0000-4000-8000-000000000000"}'

Be sure to set the correct values for gameId, winCode, and your bearer token.

What's my score?

Scores can be retreived thusly:

curl "https://angstloch.io/api/score"

Can I set my own bearer token?

No, but you can get a new one.

curl "https://angstloch.io/api/token" -H "Authorization: Bearer 00000000-0000-4000-8000-000000000000"

How do I change my playerId?

playerIds can be changed on demand. It's just a value that gets shown on the score page. First come, first served. Don't be rude.

curl "https://angstloch.io/api/player" -H "accept: application/json" -H "Authorization: Bearer 00000000-0000-4000-8000-000000000000" -H  "Content-Type: application/json" -d '{"playerId":"JaneDoe"}'

Do I have to use CURL?

No. It's just a REST API. Help yourself.

Couldn't you have just made a regular login page and some web forms?

Yes, I could have. But angstloch.io's games are a DIY experience.

What else can I do?

Nothing, yet.

API Spec

openapi: 3.0.0
info:
  version: "1.0.0"
  title: angstloch.io Game API
  description: Claim victory for winning angstloch.io games!
  contact:
    email: angstloch@protonmail.com
paths:
  /claim:
    post:
      description: |
          Prove you have a valid winCode. Also for account creation.
          You must set a "Authentication: Bearer xxx" request header for claims
          after your first. A bearerToken is provided in response to your first
          valid claim request.
      security:
        - bearerToken: []
      responses:
        '201':
          description: It worked.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  playerId:
                    type: string
                    description: Appears if you registered an account.
                  bearerToken:
                    type: string
                    format: uuid
                    description: |
                      Uniquely identifies your account for further claims.                          
                      This value must be provided in an HTTP request header as
                      "Authentication: Bearer xxx".
                      It is provided only once. If you lose it you are out of luck.
        '400':
          description: Didn't work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
        '401':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
        '409':
          description: |
            Conflict! Either the player had already claimed the wincode, or the
            given playerId is in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - gameId
                - winCode
              properties:
                gameId:
                  type: string
                  example: PA1challenge1
                winCode:
                  type: string
                  format: uuid
                playerId:
                  type: string
                  example: JohnDoe
                  description: |
                    Player's display name. Must be set on initial claim. Ignored
                    subsequently. 
  /player:
    post:
      description: |
        Change your playerId.            
        Requires a valid "Authentication: Bearer xxx" request header.
      security:
        - bearerToken: []
      responses:
        '200':
          description: It worked.
        '401':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
        '409':
          description: Conflict. The given playerId is in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - playerId
              properties:
                playerId:
                  type: string
                  example: JohnDoe
                  description: New name. 
  /score:
    get:
      description: Get current scores.
      responses:
        '200':
          description: It worked.
          content:
            text/plain:
              schema:
                type: string
  /token:
    get:
      description: |
        Get a new bearerToken.
        Requires a valid "Authentication: Bearer xxx" request header.
      security:
        - bearerToken: []
      responses:
        '200':
          description: It worked.
          content:
            application/json:
              schema:
                properties:
                  bearerToken:
                    type: string
                    format: uuid
        '400':
          description: Didn't work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
        '401':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorMessage'
servers:
  - url: 'https://angstloch.io/api'
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: UUID
  schemas:
    errorMessage:
      type: object
      properties:
        message:
          type: string