Indian Institute of Technology Kanpur return_claims API

openapi: 3.0.3
info:
  contact:
    name: Koha Development Team
    url: https://koha-community.org/
  description: "## Background\n\nThe API supports two sets of endpoints, one targetted at library staff and the other at at library users.\n\nThose endpoints under the `/public` path are aimed at delivering functionality tailored to library users and offer\na more restricted set of functions, overrides and data in thier responses for data privacy and library policy\nreasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated\nsession will expose additional options and allow users to see more data where it is part of their own record.\n\nAll other endpoints are targetted at the staff interface level and allow for additional functionality and a more\nunrestricted view of data.  These endpoints, however, have a level of redaction built in for resources that the\napi consumer should not have access to.  For example, user data for users who do not belong to the same library\nor library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will\nbe consistent for all responses, but their values may be removed depending on access.\n\n## Authentication\n\nThe API supports the following authentication mechanisms\n\n* HTTP Basic authentication\n* OAuth2 (client credentials grant)\n* Cookie-based\n\nBoth _Basic authentication_ and the _OAuth2_ flow, need to be enabled\nby system preferences.\n\n## Authorization\n\nThe API uses existing user profiles to restrict access to resources based on user permissions and the library the\nAPI user is assigned to.  This may result, at times, in resources being returned in a redacted form with all keys\npresent but sensative values nulled.\n\nWe do not yet support OAuth Scopes or the Authorization Code grant flow.\n\n## Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following format:\n\n```\n{\n  \"error\": \"Current settings prevent the passed due date to be applied\",\n  \"error_code\": \"invalid_due_date\"\n}\n```\n\nNote: Some routes might offer additional attributes in their error responses but that\"s\nsubject to change and thus not documented.\n\n## Filtering responses\n\nThe API allows for some advanced response filtering using a JSON based query syntax. The\nquery can be added to the requests:\n\n* as a query parameter `q=`\n* in the request body\n\nFor simple field equality matches we can use `{ \"fieldname\": \"value\" }` where the fieldname\nmatches one of the fields as described in the particular endpoints response object.\n\nWe can refine that with more complex matching clauses by nesting a the clause into the\nobject; `{ \"fieldname\": { \"clause\": \"value\" } }`.\n\nAvailable matching clauses include `=`, `!=`, `<`, `>`, `<=`, `>=` and `-not`. We also support `-like`\nand `-not_like` string comparisons with `%` used to denote wildcards, thus you can pass\n`{ \"fieldname\": { \"-like\": \"value%\" } }` to do a 'starts with' string match for example.\n\nWe can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`\nlevel will result in an \"AND\" query, whilst combinding them in an `ARRAY` will result in an\n\"OR\" query: `{ \"field1\": \"value2\", \"field2\": \"value2\" }` will filter the response to only those\nresults with both field1 containing value2 AND field2 containing value2 for example.\n\nThere is a collection of special operators also available to you, including:\n\n* `-in` - Expects an array of values to perform an OR match against\n* `-not_in` - Expects an array of values to perform a NOR match against\n* `-between` - Expects two values which the value of the field is expected to fall between\n* `-not_between` - Expects two values which the value of the field is expected to fall outside of\n* `-ident` - Expects a second field name to match the two field values against\n* `-regexp` - Expects a perl compatible regular expression for which the value should match\n\nLogic and nesting is also supported and you may use `-and` and `-or` to change the logic of an ARRAY\nor HASH as described above.\n\nAdditionally, if you are requesting related data be embedded into the response one can query\non the related data using dot notation in the field names.\n\n### Examples\n\nThe following request would return any patron with firstname \"Henry\" and lastname \"Acevedo\";\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": \"Acevedo\", \"firstname\": \"Henry\" }'`\n\nThe following request would return any patron whose lastname begins with \"Ace\";\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": { \"-like\": \"Ace%\" }'`\n\nThe following request would return any patron whose lastname is \"Acevedo\" OR \"Bernardo\"\n\n`curl -u koha:koha --request GET \"http://127.0.0.1:8081/api/v1/patrons/\" --data-raw '{ \"surname\": [ \"Acevedo\", \"Bernardo\" ] }'`\n\nThe following request embeds the related patron extended attributes data and filters on it.\n\n`curl -u koha:koha =--request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header 'x-koha-embed: extended_attributes' --data-raw '{ \"extended_attributes.code\": \"internet\", \"extended_attributes.attribute\": \"1\" }'`\n\n## Special headers\n\n### x-koha-embed\n\nThis optional header allows the api consumer to request additional related data\nto be returned in the api response.  It also allows for cross referencing in the\nqueries as described above. It accepts a comma delimited list of relation names.\n\nRelations may on occasion also support dot delimited nesting to allow traversal.\n\n### x-koha-library\n\nThis optional header should be passed to give your api request a library\ncontext; If it is not included in the request, then the request context\nwill default to using your api comsumer\"s assigned home library.\n"
  license:
    name: GPL v3,
    url: http://www.gnu.org/licenses/gpl.txt
  title: Koha REST 2fa return_claims API
  version: '1'
servers:
- url: https://libserv.iitk.ac.in/api/v1
  description: PKK Library Koha REST API (production)
tags:
- description: 'Manage return claims

    '
  name: return_claims
  x-displayName: Return claims
paths:
  /return_claims:
    post:
      tags:
      - return_claims
      summary: Add a return claim
      operationId: claimReturned
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                charge_lost_fee:
                  description: Charge a lost fee if true and Koha is set to allow a choice. Ignored otherwise.
                  type: boolean
                created_by:
                  description: User id for the librarian submitting this claim
                  type: string
                item_id:
                  description: Internal item id to claim as returned
                  type: integer
                notes:
                  description: Notes about this return claim
                  type: string
              type: object
        description: A JSON object containing fields to modify
      responses:
        '201':
          description: Created claim
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return_claim_yaml'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Checkout not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '409':
          description: Conflict creating the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '503':
          description: Under maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
  /return_claims/{claim_id}:
    delete:
      tags:
      - return_claims
      summary: Delete claim
      operationId: deletedClaim
      parameters:
      - name: claim_id
        in: path
        required: true
        description: Unique identifier for the claim to be deleted
        schema:
          type: integer
      responses:
        '204':
          description: Claim deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return_claim_yaml'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '503':
          description: Under maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
  /return_claims/{claim_id}/notes:
    put:
      tags:
      - return_claims
      summary: Update notes
      operationId: updateClaimNotes
      parameters:
      - name: claim_id
        in: path
        required: true
        description: Unique identifier for the claim whose notes are to be updated
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                notes:
                  description: Notes about this return claim
                  type: string
                updated_by:
                  description: Interal identifier for the librarian updating the claim notes
                  type: string
              type: object
        description: A JSON object containing fields to modify
      responses:
        '200':
          description: Claim notes updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return_claim_yaml'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '503':
          description: Under maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
  /return_claims/{claim_id}/resolve:
    put:
      tags:
      - return_claims
      summary: Resolve claim
      operationId: updateClaimResolve
      parameters:
      - name: claim_id
        in: path
        required: true
        description: Unique identifier for the claim to be resolved
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                new_lost_status:
                  description: New lost status to set to the item
                  type: string
                resolution:
                  description: The RETURN_CLAIM_RESOLUTION code to be used to resolve the calim
                  type: string
                resolved_by:
                  description: User id for the librarian resolving the claim
                  type: string
              type: object
        description: A JSON object containing fields to modify
      responses:
        '200':
          description: Claim resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return_claim_yaml'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '503':
          description: Under maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
components:
  schemas:
    return_claim_yaml:
      additionalProperties: false
      properties:
        claim_id:
          description: internally assigned return claim identifier
          type:
          - integer
        created_by:
          description: patron id of librarian who made the claim
          type:
          - integer
          - 'null'
        created_on:
          description: date of claim creation
          format: date-time
          type:
          - string
          - 'null'
        issue_id:
          description: internal identifier of the claimed checkout if still checked out
          type:
          - integer
          - 'null'
        item_id:
          description: internal identifier of the claimed item
          type:
          - integer
        notes:
          description: notes about this claim
          type:
          - string
          - 'null'
        old_issue_id:
          description: internal identifier of the claimed checkout if not longer checked out
          type:
          - integer
          - 'null'
        patron_id:
          description: Internal patron identifier
          type: integer
        resolution:
          description: code of resolution type for this claim
          type:
          - string
          - 'null'
        resolved_by:
          description: patron id of librarian who resolved this claim
          type:
          - integer
          - 'null'
        resolved_on:
          description: date the claim was resolved
          format: date-time
          type:
          - string
          - 'null'
        updated_by:
          description: patron id of librarian who last updated the claim
          type:
          - integer
          - 'null'
        updated_on:
          description: date the claim was last updated
          format: date-time
          type:
          - string
          - 'null'
      type: object
    error_yaml:
      additionalProperties: true
      properties:
        error:
          description: Error message
          type: string
        error_code:
          description: Error code
          type: string
      type: object
    DefaultResponse:
      properties:
        errors:
          items:
            properties:
              message:
                type: string
              path:
                type: string
            required:
            - message
            type: object
          type: array
      required:
      - errors
      type: object