instance-storage.raml

#%RAML 1.0
title: Instance Storage
version: v10.0
protocols: [ HTTP, HTTPS ]
baseUri: http://localhost

documentation:
  - title: Instance Storage API
    content: <b>Storage for instances in the inventory</b>

types:
  instance: !include instance.json
  instances: !include instances.json
  marcJson: !include marc.json
  instanceRelationship: !include instancerelationship.json
  instanceRelationships: !include instancerelationships.json

traits:
  language: !include raml-util/traits/language.raml
  pageable: !include raml-util/traits/pageable.raml
  searchable: !include raml-util/traits/searchable.raml

resourceTypes:
  collection: !include raml-util/rtypes/collection.raml
  collection-item: !include raml-util/rtypes/item-collection.raml

/instance-storage:
  /instance-relationships:
    displayName: Hierarchical relations between Instances
    type:
      collection:
        exampleCollection: !include  examples/instancerelationships_get.json
        schemaCollection: instanceRelationships
        schemaItem: instanceRelationship
        exampleItem: !include  examples/instancerelationship_get.json
    get:
      is: [pageable,
          searchable: {description: "by parent ID or by child ID (using CQL)",
                       example: "subInstanceId==83a50dc6-b887-43d9-93ee-28b2c4cd11f8
                                 superInstanceId==30fcc8e7-a019-43f4-b642-2edc389f4501
                                 instanceRelationshipTypeId==758f13db-ffb4-440e-bb10-8a364aa6cb4a AND superInstanceId=30fcc8e7-a019-43f4-b642-2edc389f4501"},
          ]
    post:
    /{relationshipId}:
      type:
        collection-item:
          exampleItem: !include examples/instancerelationship_get.json
          schema: instanceRelationship
      get:
        responses:
          200:
            body:
              application/json:
                type: instanceRelationship
        description: |
          Get Instance Relationship
  /instances:
    displayName: Instances
    type:
      collection:
        exampleCollection: !include  examples/instances_get.json
        schemaCollection: instances
        schemaItem: instance
        exampleItem: !include  examples/instance_get.json
    get:
      is: [pageable,
          searchable: {description: "by title (using CQL)",
                        example: "title=\"*uproot*\""},
          ]
    post:
    delete:
      is: [searchable: { description: "CQL to select instances to delete, use cql.allRecords=1 to delete all. Deletes connected marc source records.",
                         example: "hrid==\"in123-0*\"" } ]
      responses:
        204:
          description: "Selected instances deleted"
        400:
          description: "Bad request, e.g. malformed query parameter"
          body:
            text/plain:
              example: "query parameter is empty"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    /{instanceId}:
      type:
        collection-item:
          exampleItem: !include examples/instance_get.json
          schema: instance
      get:
        responses:
          200:
            body:
              application/json:
                type: instance
        description: |
          Get Instance by InstanceId
          Instances are stored and accessed by a hash of key properties. The rules which govern
          how instance hashes are computed are business rules and defined in the service layer.
          the storage layer only knows how to insert or retrieve instance records by ID.
      /source-record:
        delete:
          is: [language]
          responses:
            204:
              description: "Source record deleted"
            400:
              description: "Bad request"
              body:
                text/plain:
                  example: "This MARC record is still in use"
            404:
              description: "There is no source record for that instanceId"
              body:
                text/plain:
                  example: "There is no source record for that instanceId"
            500:
              description: "Internal server error, e.g. due to misconfiguration"
              body:
                text/plain:
                  example: "Internal server error, contact administrator"
          description: |
            Delete the source record.
            Note: When the Inventory instance record is deleted, its source record in mod-inventory-storage is automatically deleted. If the Inventory instance record is linked to a corresponding record in mod-source-record-storage, that SRS record is NOT automatically deleted.
        /marc-json:
          displayName: MARC source record as JSON
          is: [language]
          type:
            collection-item:
              exampleItem: !include examples/marc.json
              schema: marcJson
        /mods:
          displayName: MODS source record - not implemented yet
          is: [language]
          get:
            responses:
              500:
                description: "Not implemented yet"
                body:
                  text/plain:
                    example: "Not implemented yet"
          put:
            responses:
              500:
                description: "Not implemented yet"
                body:
                  text/plain:
                    example: "Not implemented yet"