Sample-Module (v1)

http://github.com/org/folio/sample-module

Table of contents

Sample Module

CRUD API

/details

Collection of detail items.

GET /details

Get list of details

GET /details
Query Parameters
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    with valid searchable fields: for example code

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    ["code", "MEDGRANT", "="]
    
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of detail items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "collection of detail records",
  "type": "object",
  "properties": {
    "details": {
      "description": "collection of detail records",
      "type": "array",
      "id": "details",
      "items": {
        "type": "object",
        "$ref": "details.json"
      }
    },
    "total_records": {
      "description": "The number of objects contained in this collection",
      "type": "integer"
    },
    "first": {
      "description": "The index of the first object contained in this collection",
      "type": "integer"
    },
    "last": {
      "description": "The index of the last object contained in this collection",
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "details",
    "total_records"
  ]
}

Example:

{
    "details":
        [
          {
            "id": "349d9438-12bd-4e2e-9eb6-dfa830ab99a4",
            "receiving_note": "ABCDEFGHIJKL",
            "product_ids": [
              {
                "product_id": "9780764354113",
                "product_id_type": "ISBN"
              }
            ],
            "material_types": [
              "f7e72403-2a13-43a4-a069-aaabe6c9dea8"
            ],
            "subscription_from": "2018-10-09T00:00:00.000Z",
            "subscription_interval": 824,
            "subscription_to": "2020-10-09T00:00:00.000Z",
            "po_line_id": "8c778aee-97fa-4586-b131-3ea588a728e2"
          }
        ],
    "total_records": 1,
    "first": 1,
    "last": 1
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list details -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list details -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /details

Create a new detail item.

POST /details
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "purchase order line details",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID for this details record",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "receiving_note": {
      "description": "notes regarding receiving instructions",
      "type": "string"
    },
    "product_ids": {
      "description": "a list of product identifiers",
      "id": "product_ids",
      "type": "array",
      "items": {
        "description": "a product identifier",
        "type": "object",
        "properties": {
          "product_id": {
            "description": "the actual id",
            "type": "string"
          },
          "product_id_type": {
            "description": "the type of id",
            "type": "string",
            "enum": [
              "ISBN",
              "ISSN",
              "ISMN",
              "EAN",
              "Other Standard Identifier",
              "Standard Technical Report Number",
              "Publisher Number",
              "CODEN",
              "GPO Item Number",
              "Locally-defined identifiers",
              "Vendor Title Number",
              "Vendor Item Number"
            ]
          }
        }
      }
    },
    "material_types": {
      "description": "a list of material type ids",
      "id": "material_type",
      "type": "array",
      "items": {
        "description": "UUID associated with this material's type",
        "type": "string",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
      }
    },
    "subscription_from": {
      "description": "the start date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "subscription_interval": {
      "description": "the subscription interval in days",
      "type": "integer"
    },
    "subscription_to": {
      "description": "the end date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "po_line_id": {
      "description": "UUID of the purchase order line these details relate to",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    }
  },
  "additionalProperties": false
}

Example:

{
  "receiving_note": "ABCDEFGHIJKL",
  "product_ids": [
    {
      "product_id": "9780764354113",
      "product_id_type": "ISBN"
    }
  ],
  "material_types": [
    "f7e72403-2a13-43a4-a069-aaabe6c9dea8"
  ],
  "subscription_from": "2018-10-09T00:00:00.000Z",
  "subscription_interval": 824,
  "subscription_to": "2020-10-09T00:00:00.000Z",
  "po_line_id": "8c778aee-97fa-4586-b131-3ea588a728e2"
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created detail item

Body

Media type: application/json

Type: any

Example:

{
  "receiving_note": "ABCDEFGHIJKL",
  "product_ids": [
    {
      "product_id": "9780764354113",
      "product_id_type": "ISBN"
    }
  ],
  "material_types": [
    "f7e72403-2a13-43a4-a069-aaabe6c9dea8"
  ],
  "subscription_from": "2018-10-09T00:00:00.000Z",
  "subscription_interval": 824,
  "subscription_to": "2020-10-09T00:00:00.000Z",
  "po_line_id": "8c778aee-97fa-4586-b131-3ea588a728e2"
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add detail -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create details -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /details/{id}

Retrieve detail item with given {detailId}

GET /details/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "purchase order line details",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID for this details record",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "receiving_note": {
      "description": "notes regarding receiving instructions",
      "type": "string"
    },
    "product_ids": {
      "description": "a list of product identifiers",
      "id": "product_ids",
      "type": "array",
      "items": {
        "description": "a product identifier",
        "type": "object",
        "properties": {
          "product_id": {
            "description": "the actual id",
            "type": "string"
          },
          "product_id_type": {
            "description": "the type of id",
            "type": "string",
            "enum": [
              "ISBN",
              "ISSN",
              "ISMN",
              "EAN",
              "Other Standard Identifier",
              "Standard Technical Report Number",
              "Publisher Number",
              "CODEN",
              "GPO Item Number",
              "Locally-defined identifiers",
              "Vendor Title Number",
              "Vendor Item Number"
            ]
          }
        }
      }
    },
    "material_types": {
      "description": "a list of material type ids",
      "id": "material_type",
      "type": "array",
      "items": {
        "description": "UUID associated with this material's type",
        "type": "string",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
      }
    },
    "subscription_from": {
      "description": "the start date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "subscription_interval": {
      "description": "the subscription interval in days",
      "type": "integer"
    },
    "subscription_to": {
      "description": "the end date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "po_line_id": {
      "description": "UUID of the purchase order line these details relate to",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    }
  },
  "additionalProperties": false
}

Example:

{
  "id": "349d9438-12bd-4e2e-9eb6-dfa830ab99a4",
  "receiving_note": "ABCDEFGHIJKL",
  "product_ids": [
    {
      "product_id": "9780764354113",
      "product_id_type": "ISBN"
    }
  ],
  "material_types": [
    "f7e72403-2a13-43a4-a069-aaabe6c9dea8"
  ],
  "subscription_from": "2018-10-09T00:00:00.000Z",
  "subscription_interval": 824,
  "subscription_to": "2020-10-09T00:00:00.000Z",
  "po_line_id": "8c778aee-97fa-4586-b131-3ea588a728e2"
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"detail not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /details/{id}

Delete detail item with given {detailId}

DELETE /details/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete detail -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"detail not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /details/{id}

Update detail item with given {detailId}

PUT /details/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "purchase order line details",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID for this details record",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "receiving_note": {
      "description": "notes regarding receiving instructions",
      "type": "string"
    },
    "product_ids": {
      "description": "a list of product identifiers",
      "id": "product_ids",
      "type": "array",
      "items": {
        "description": "a product identifier",
        "type": "object",
        "properties": {
          "product_id": {
            "description": "the actual id",
            "type": "string"
          },
          "product_id_type": {
            "description": "the type of id",
            "type": "string",
            "enum": [
              "ISBN",
              "ISSN",
              "ISMN",
              "EAN",
              "Other Standard Identifier",
              "Standard Technical Report Number",
              "Publisher Number",
              "CODEN",
              "GPO Item Number",
              "Locally-defined identifiers",
              "Vendor Title Number",
              "Vendor Item Number"
            ]
          }
        }
      }
    },
    "material_types": {
      "description": "a list of material type ids",
      "id": "material_type",
      "type": "array",
      "items": {
        "description": "UUID associated with this material's type",
        "type": "string",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
      }
    },
    "subscription_from": {
      "description": "the start date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "subscription_interval": {
      "description": "the subscription interval in days",
      "type": "integer"
    },
    "subscription_to": {
      "description": "the end date of the subscription",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "po_line_id": {
      "description": "UUID of the purchase order line these details relate to",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    }
  },
  "additionalProperties": false
}

Example:

{
  "id": "349d9438-12bd-4e2e-9eb6-dfa830ab99a4",
  "receiving_note": "ABCDEFGHIJKL",
  "product_ids": [
    {
      "product_id": "9780764354113",
      "product_id_type": "ISBN"
    }
  ],
  "material_types": [
    "f7e72403-2a13-43a4-a069-aaabe6c9dea8"
  ],
  "subscription_from": "2018-10-09T00:00:00.000Z",
  "subscription_interval": 824,
  "subscription_to": "2020-10-09T00:00:00.000Z",
  "po_line_id": "8c778aee-97fa-4586-b131-3ea588a728e2"
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update detail -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"detail not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator