api.raml

#%RAML 1.0
title: flatr
version: v0.2.1
mediaType: application/json
protocols: [ HTTP ]

traits:
  fallible:
    responses:
      400:
        body:
          type: Error
          examples:
            bad_request: |
              {
                "error": {
                  "code": "bad_json",
                  "message": "The JSON request payload could not be parsed."
                }
              }
  findable:
    responses:
      404:
        body:
          type: Error
          examples:
            not_found: |
              {
                "error": {
                  "code": "not_found",
                  "message": "The resource you requested could not be found."
                }
              }
  restricted:
    headers:
      Authorization:
        description: Auth token
        example: |
          Bearer $token
    responses:
      401:
        body:
          type: Error
          examples:
            unauthorized: |
              {
                "error": {
                  "code": "unauthorized",
                  "message": "You are not authorized to access this resource."
                }
              }

types: !include ./types.raml

/info:
  get:
    description: Get info about the API server
    responses:
      200:
        body:
          type: Info

/invitations:
  get:
    is: [ restricted ]
    description: Get all pending invitations
    responses:
      200:
        body:
          type: Invitation[]
          example: |
            [
              {
                "id": 1,
                "email": "flatmate@example.com"
              },
              {
                "id": 3,
                "email": "landlord@example.com"
              }
            ]
  post:
    is: [ restricted, fallible ]
    description: |
      Invite a person via email address. An email with invite code is sent to them
    body:
      type: object
      properties:
        email: string
      example: |
        {
          "email": "flatmate@example.com"
        }
    responses:
      201:
        headers:
          Location:
            description: URL of the newly created Invitation
        body:
          type: Invitation
      409:
        body:
          type: Error
          examples:
            invitation_email_exists: |
              {
                "error": {
                  "code": "invitation_email_exists",
                  "message": "An invitation with this email address already exists."
                }
              }
  /{invitationId}:
    uriParameters:
      invitationId:
        type: integer
    get:
      is: [ restricted, findable ]
      description: Get information about a specific invitation
      responses:
        200:
          body:
            type: Invitation
    patch:
      is: [ restricted, findable, fallible ]
      description: Resend invitation email
      body:
        example: {}
      responses:
        200:
          body:
            type: Invitation
    delete:
      is: [ restricted, findable ]
      description: Delete/Invalidate this invitation
      responses:
        204:
          description: Invitation was successfully deleted

/tasks:
  get:
    is: [ restricted ]
    description: |
      List all tasks
    responses:
      200:
        body:
          type: Task[]
          example: |
            [
              {
                "id": 1,
                "title": "Doing the dishes",
                "description": "Use soap!",
                "frequency": 3,
                "completionTime": 5,
                "users": [
                  1
                ],
                "currentTurn": {
                  "userId": 1,
                  "startDate": "2018-02-12T04:46:59.234975184Z"
                },
                "upcomingTurns": [
                  {
                    "userId" : 3,
                    "startDate": "2018-02-15T07:00:23.233925184Z"
                  }
                ]
              }
            ]
  post:
    is: [ restricted, fallible ]
    description: |
      Add a new task
    body:
      type: RequestTask
      example: |
        {
          "title": "Doing the dishes",
          "description": "It ain't difficult.",
          "frequency": 3,
          "completionTime": 5,
          "users": [
            1
          ]
        }
    responses:
      201:
        headers:
          Location:
            description: URL of the newly created task
        body:
          type: Task
          example: |
            {
              "id": 1,
              "title": "Doing the dishes",
              "description": "Wow, another description here!",
              "frequency": 3,
              "completionTime": 5,
              "users": [
                1
              ],
              "currentTurn": {
                "userId": 1,
                "startDate": "2018-02-12T04:46:59.234975184Z"
              },
              "upcomingTurns": [
                {
                  "userId" : 3,
                  "startDate": "2018-02-15T07:00:23.233925184Z"
                }
              ]
            }
  /{taskId}:
    uriParameters:
      taskId:
        type: integer
    get:
      is: [ restricted, findable ]
      description: |
        Get detailed information about a task
      responses:
        200:
          body:
            type: Task
            example: |
              {
                "id": 1,
                "title": "Doing the dishes",
                "description": "This should explain what to do...",
                "frequency": 3,
                "completionTime": 5,
                "users": [
                  1
                ],
                "currentTurn": {
                  "userId": 1,
                  "startDate": "2018-02-12T04:46:59.234975184Z"
                },
                "upcomingTurns": [
                  {
                    "userId" : 3,
                    "startDate": "2018-02-15T07:00:23.233925184Z"
                  }
                ]
              }
    delete:
      is: [ restricted, findable ]
      description: |
        Delete a task
      responses:
        204:
          description: |
            Task was successfully deleted
    put:
      is: [ restricted, findable, fallible ]
      description: |
        Replace a task and return the same one
      body:
        type: RequestTask
        example: |
          {
            "title": "Doing the dishes",
            "description": "Pretty obvious what to do...",
            "frequency": 3,
            "completionTime": 5,
            "users": [
              1
            ]
          }
      responses:
        200:
          body:
            type: Task
            example: |
              {
                "id": 1,
                "title": "Doing the dishes",
                "description": "Pretty obvious what to do...",
                "frequency": 3,
                "completionTime": 5,
                "users": [
                  1
                ],
                "currentTurn": null,
                "upcomingTurns": [
                  {
                    "userId" : 3,
                    "startDate": "2018-02-15T07:00:23.233925184Z"
                  }
                ]
              }
    /finish:
      post:
        is: [ restricted, findable ]
        description: Finish the currently active turn of this task
        responses:
          204:
            description: Task was successfully finished

/auth:
  post:
    is: [ fallible ]
    description: Authenticate yourself
    body:
      type: LoginCredentials
      example: |
        {
          "email": "john.doe@example.org",
          "password": "pa$$w0rd"
        }
    responses:
      200:
        body:
          type: TokenResponse
          example: |
            {
              "token": "header.payload.signature",
              "tokenId": "_tokenId000000000000",
              "validFor": 3600
            }
      403:
        body:
          type: Error
          examples:
            email_not_verified: |
              {
                "error": {
                  "code": "email_not_verified",
                  "message": "You have not verified your email address yet."
                }
              }
            credentials_wrong: |
              {
                "error": {
                  "code": "credentials_wrong",
                  "message": "User does not exist or password is wrong."
                }
              }
            user_disabled: |
              {
                "error": {
                  "code": "user_disabled",
                  "message": "This user is disabled and has to be enabled before being able to log in."
                }
              }

/users:
  get:
    is: [ restricted ]
    description: Get all users
    responses:
      200:
        body:
          type: User[]
          example: |
            [
              {
                "id": 1,
                "email": "ds@example.org",
                "firstName": "Daniel",
                "lastName": "Schäfer",
                "emailVerified": true,
                "disabled": false,
                "absent": false
              }
            ]
  post:
    is: [ fallible ]
    description: Register a new user
    body:
      type: InvitationRegistration | EmailRegistration
      examples:
        with_invitation_code: |
          {
            "firstName": "Daniel",
            "lastName": "Schäfer",
            "password": "pa$$w0rd",
            "invitationCode": "9d0d1e5f8dbe5dc0",
            "absent": false
          }
        with_email: |
          {
            "firstName": "Daniel",
            "lastName": "Schäfer",
            "password": "pa$$w0rd",
            "email": "foo@example.org",
            "absent": false
          }
    responses:
      200:
        body:
          type: User
      409:
        body:
          type: Error
          examples:
            email_exists: |
              {
                "error": {
                  "code": "email_exists",
                  "message": "A user with this email address already exists."
                }
              }
      403:
        body:
          type: Error
          examples:
            invitation_code_invalid: |
              {
                "error": {
                  "code": "invitation_code_invalid",
                  "message": "This is not a valid invitation code."
                }
              }
      401:
        body:
          type: Error
          examples:
            not_invite: |
              {
                "error": {
                  "code": "not_invited",
                  "message": "Your email address is not invited."
                }
              }
  /{userId}:
    get:
      is: [ restricted, findable ]
      description: |
        Get the user with this Id
      responses:
        200:
          body:
            type: User
    delete:
      is: [ restricted, findable ]
      description: |
        Delete the user with this id
      responses:
        204:
          description: User was successfully deleted
  /verify:
    post:
      is: [ fallible ]
      description: |
        Verify the email of a user by providing the code
        sent to him in an email.
      body:
        type: object
        properties:
          code: string
      responses:
        200:
          body:
            type: User
        403:
          body:
            type: Error
            examples:
              verification_code_invalid: |
                {
                  "error": {
                    "code": "verification_code_invalid",
                    "message": "Your email address could not be verified with this code."
                  }
                }
  /current:
    get:
      is: [ restricted ]
      description: |
        Get the currently logged in user
      responses:
        200:
          body:
            type: User