doorbot.openapi3_0.yaml

openapi: 3.0.0
info:
  title: Bodgery Auth API
  description: |-
    Authenticates and authorizes Bodgery members for doors, tools, etc.

  contact:
    email: tmurray@wumpus-cave.net
  version: 1.1.0
servers:
  - url: https://rfid-prod.shop.thebodgery.org
  - url: https://rfid-dev.shop.thebodgery.org  
tags:
  - name: rfid
    description: RFID tag for a member
  - name: location
    description: A part of the Bodgery a member might access, like a tool or a door
paths:
  /check_tag/{rfid}:
    get:
      deprecated: true
      tags:
        - rfid
      summary: Check if an RFID tag is valid. DEPRECATED--use /secure/check_tag/{rfid}/{location} instead
      description: Check if an RFID tag is valid. DEPRECATED--use /secure/check_tag/{rfid}/{location} instead
      operationId: check_tag
      responses:
        '200':
          description: Tag is found and valid
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tag was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Tag was found, but not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/check_tag/{rfid}/{location}:
    get:
      tags:
        - rfid
        - location
      summary: Check if an RFID tag is valid for a given location
      description: Check if an RFID tag is valid for a given location
      operationId: check_tag_location
      responses:
        '200':
          description: Tag is found and valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tag was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
        '403':
          description: Tag was found, but not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
  /entry/{rfid}/{location}:
    get:
      tags:
        - rfid
        - location
      summary: Log that an RFID tag was given access to a location
      description: Log that an RFID tag was given access to a location. Note that this does send back response codes that indicate if the RFID tag was valid and allowed. However, its primary purpose is to log an entry that already happened
      operationId: log_entry
      responses:
        '200':
          description: Tag is found and valid for this location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Tag was not 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
        '403':
          description: Tag was found, but not active for this location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryResponse'
  /v1/new_tag/{rfid}/{full_name}:
    put:
      tags:
        - rfid
      summary: Add a new RFID tag with the given member name
      description: Add a new RFID tag with the given member name.
      operationId: new_tag
      responses:
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '201':
          description: New RFID tag added
  /v1/deactivate_tag/{rfid}:
    post:
      tags:
        - rfid
      summary: Deactivate an RFID tag
      description: Deactivate an RFID tag
      operationId: deactivate_tag
      responses:
        '200':
          description: Tag was deactivated
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/reactivate_tag/{rfid}:
    post:
      tags:
        - rfid
      summary: Reactivate an RFID tag
      description: Reactivate an RFID tag
      operationId: reactivate_tag
      responses:
        '200':
          description: Tag was reactivated
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/edit_tag/{current_rfid}/{new_rfid}:
    post:
      tags:
        - rfid
      summary: Replace an old RFID tag with a new one
      description: Replace an old RFID tag with a new one
      operationId: edit_tag
      responses:
        '201':
          description: Tag was changed
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/edit_name/{rfid}/{new_name}:
    post:
      tags:
        - rfid
      summary: Change the name attached to an RFID
      description: Change the name attached to an RFID
      operationId: edit_name
      responses:
        '201':
          description: Name was changed
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/search_tags:
    get:
      summary: Search for tags
      description: Search for tags
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Search for a given name. Case insenstive. Not anchored to the start of the string.
        - in: query
          name: tag
          schema:
            type: string
          description: Search for an RFID tag. Exact match.
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
          description: Pagination. starts the response after the offset number.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Pagination. limits the number of responses
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SearchMembersResults'
  /v1/search_entry_log:
    get:
      summary: Search logs
      description: Search logs
      parameters:
        - in: query
          name: tag
          schema:
            type: string
          description: Search for an RFID tag. Exact match.
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
          description: Pagination. starts the response after the offset number.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Pagination. limits the number of responses
      responses:
        '200':
          description: Search results. This comes as a CSV. Fields are full name, RFID, entry time, was tag active at that time, was tag found at that time, and the location.
          content:
            text/csv:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEntryLogResults'
  /secure/dump_active_tags:
    get:
      deprecated: true
      summary: Dump all currently active tags. DEPRECATED--use /secure/dump_active_tags/{location} instead.
      description: Dump all currently active tags. DEPRECATED--use /secure/dump_active_tags/{location} instead.
      tags:
        - rfid
      responses:
        '200':
          description: All active tags
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties:
                    type: boolean
  /v1/dump_active_tags/{location}:
    get:
      summary: Dump all currently active tags for the given location 
      description: Dump all currently active tags for the given location 
      tags:
        - rfid
        - location
      responses:
        '200':
          description: All active tags for the given location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DumpActiveTagsResponse'
        '404':
          description: Unknown location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/change_passwd:
    put:
      summary: Change password on signed in user
      description: Change password on signed in user
      parameters:
        - in: formData
          name: cur_pass
          schema:
            type: string
          description: Current password
        - in: formData
          name: new_pass
          schema:
            type: string
          description: New password
        - in: formData
          name: new_pass2
          schema:
            type: string
          description: New password; verified to match new_pass
      responses:
        '200':
          description: Password changed
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/change_passwd/{rfid}:
    put:
      summary: Change password on the given user
      description: Change password the given user
      tags:
        - rfid
      parameters:
        - in: formData
          name: new_pass
          schema:
            type: string
          description: New password
        - in: formData
          name: new_pass2
          schema:
            type: string
          description: New password; verified to match new_pass
      responses:
        '200':
          description: Password changed
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/role/{role}/{rfid}:
    put:
      summary: Give access to a role to the user
      description: Give access to a role to the user. If the role does not exist, it will be created.
      tags:
        - rfid
        - permission
      responses:
        '201':
          description: Role added to user
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Current user does not have rights to grant this access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Remove access to a role from user
      description: Remove access to a role from the user
      tags:
        - rfid
        - permission
      responses:
        '200':
          description: Role removed from user
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Current user does not have rights to remove this access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Either the role or the member was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/permission/{permission}/{role}:
    put:
      summary: Add a permission to a role
      description: Add a permission to a role. If the role or permission does not exist, they will be created.
      tags:
        - permission
      responses:
        '201':
          description: Permission added to role
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Current user does not have rights to grant this access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Remove a permission from a role
      description: Remove a permission from a role
      tags:
        - permission
      responses:
        '200':
          description: Access removed
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Current user does not have rights to remove this access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Either the permission or the role was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    EntryResponse:
      type: object
      required:
        - full_name
        - rfid
        - location
      properties:
        full_name:
          type: string
          example: 'Jane Doe'
        rfid:
          type: string
          example: '0001234567'
        location:
          type: string
          example: 'woodshop.door'
        active:
          type: boolean
        found:
          type: boolean
    SearchMembersResults:
      type: object
      required:
        - full_name
        - rfid
        - active
        - mms_id
      properties:
        full_name:
          type: string
          example: 'Jane Doe'
        rfid:
          type: string
          example: '0001234567'
        active:
          type: boolean
        mms_id:
          type: integer
    SearchEntryLogResults:
      type: array
      items:
        type: object
        # full name, RFID, entry time, was tag active at that time, was tag found at that time, and the location.
        required:
          - fullname
          - rfid
          - entry time
          - was_allowed
          - was_found
          - location
        properties:
          full_name:
            type: string
            example: 'Jane Doe'
          rfid:
            type: string
            description: 'ISO8601 date string'
            example: '0001234567'
          entry_time:
            type: string
            example: '2011-10-05T14:48:00.000Z'
          was_allowed:
            description: Was the RFID tag allowed at the time of entry
            type: boolean
          was_found:
            description: Was the RFID tag found at the time of entry
            type: boolean
          location:
            type: string
            example: 'cleanroom.door'
    DumpActiveTagsResponse:
      type: object
      additionalProperties:
        type: boolean
    ErrorResponse:
      type: object
      required:
        - msg
        - datetime
      properties:
        msg:
          type: string
        request_id:
          type: string
          description: A random string to identify the specific request
        datetime:
          type: string
          description: 'ISO8601 date string'
          example: '2011-10-05T14:48:00.000Z'