eholdings.raml

#%RAML 1.0
title: mod-kb-ebsco
baseUri: https://github.com/folio-org/mod-kb-ebsco
version: v1
mediaType: "application/vnd.api+json"

documentation:
  - title: mod-kb-ebsco (category)
    content: Implements the eholdings interface using the EBSCO kb as a backend.

traits:
  indexable:
    queryParameters:
      q:
        displayName: Query
        type: string
        description: Text entered in search field
        example: Basket Weaving
        required: true
      page:
        displayName: Page
        type: number
        description: Page offset from which results are retrieved
        example: 1
        minimum: 1
        required: false
      count:
        displayName: Count
        type: number
        description: The maximum number of results to return in the response.
        example: 10
        minimum: 0
        maximum: 100
        required: false
      sort:
        displayName: Sort options
        type: string
        enum: ["name", "relevance"]
        description: Option by which results are sorted
        default: relevance
        required: false
  filterable:
    queryParameters:
      filter[selected]:
        displayName: Selection status
        type: string
        enum: ["true", "false", "ebsco"]
        description: Filter to narrow down results based on selection status
        required: false
      filter[type]:
        displayName: Content type
        type: string
        enum: ["all", "aggregatefulltext", "abstractandindex", "ebook", "ejournal", "print", "unknown", "onlinereference"]
        description: Filter to narrow  down results based on content type
        default: all
        required: false

types:
  customCoverage: # normal object type declaration
    type: object
    properties:
      beginCoverage: string
      endCoverage: string
    example: |
      {
        "beginCoverage": "2003-01-01",
        "endCoverage": "2003-12-01"
      }
  visibilityData:
    type: object
    properties:
      isHidden: boolean
    example: |
      {
        "isHidden": true
      }
  proxy:
    type: object
    properties:
      id: string
    example: |
      {
        "id": "EZ_Proxy"
      }
  customEmbargoPeriod:
    type: object
    properties:
      embargoValue: number
      embargoUnit: string
    example: |
      {
        "embargoValue": 4,
        "embargoUnit": "Weeks"
      }
  includedPackageId:
    type: object
    properties:
      type: string
      attributes:
        properties:
          packageId: string
    example: |
      {
        "type": "resources",
        "attributes": {
          "packageId": "123-456"
        }
      }

/eholdings/packages:
  displayName: Packages
  get:
    description: Retrieve a collection of packages
    queryParameters:
      q:
        displayName: Search query
        type: string
        description: String to search for to get a collection of packages
        example: ABC-CLIO
        required: true
      page:
        displayName: Page offset
        type: integer
        minimum: 1
        maximum: 2147483647
        description: Page offset to retrieve results from Ebsco KB
        example: 1
        required: false
      count:
        displayName: Count
        type: integer
        minimum: 0
        maximum: 100
        description: Count of number of results to retrieve from Ebsco KB
        example: 100
        required: false
      sort:
        displayName: Sort options
        type: string
        enum: ["name", "relevance"]
        description: Option by which results are sorted
        example: name
        required: false
      filter[selected]:
        displayName: Selection status
        type: string
        enum: ["true", "false", "ebsco", "all"]
        description: Filter to narrow down results based on selection status
        example: "false"
        required: false
      filter[type]:
        displayName: Content type
        type: string
        enum: ["all", "aggregatedfulltext", "abstractandindex", "ebook", "ejournal", "print", "onlinereference", "unknown"]
        description: Filter to narrow down results based on content type
        example: print
        required: false
      filter[custom]:
        displayName: Custom Packages List
        type: string
        enum: ["true", "false"]
        description: Filter to get list of custom packages
        example: "true"
        required: false
    responses:
      200:
        description: OK
        body:
          application/vnd.api+json:
            example: !include examples/packages/packages_get_200_response.json
      400:
        description: Bad Request
        body:
          application/vnd.api+json:
            example: !include examples/packages/packages_get_400_response.json
  post:
    description: Create a custom package
    headers:
      Content-Type:
        example: application/vnd.api+json
    body:
      application/vnd.api+json:
        properties:
          data:
            description: Needed because of JSON API
            type: object
            required: true
            properties:
              type: string
              attributes:
                description: Needed because of JSON API
                type: object
                required: true
                properties:
                  name:
                    description: Name of the custom package to be created
                    type: string
                    example: My test package
                    required: true
                  contentType:
                    description: Content type of the custom package to be created
                    type: string
                    enum: ["all", "aggregatedfulltext", "abstractandindex", "ebook", "ejournal", "print", "onlinereference", "unknown"]
                    example: unknown
                    required: true
                  customCoverage:
                    description: Coverage dates of the custom package to be created
                    type: customCoverage
                    required: false
        example: !include examples/packages/packages_post_request.json
    responses:
      200:
        description: OK
        body:
          application/vnd.api+json:
            example: !include examples/packages/packages_post_200_response.json
      400:
        description: Bad Request
        body:
          application/vnd.api+json:
              example: !include examples/packages/packages_post_400_response.json
  /{packageId}:
    get:
      description: |
        Retrieve a specific package given packageId.
        Note that packageId is providerId-packageId
      queryParameters:
        include:
          displayName: Nested resources or provider
          type: string
          enum: ["resources", "provider"]
          description: Include resources or provider in response
          example: resources
          required: false
      responses:
        200:
          description: OK
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_get_200_response.json
        400:
          description: Bad Request
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_get_400_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_get_404_response.json
    put:
      description: |
        Update a managed or custom package using packageId
        Note that packageId is providerId-packageId
      headers:
        Content-Type:
          example: application/vnd.api+json
      body:
        application/vnd.api+json:
          properties:
            data:
              description: Needed because of JSON API
              type: object
              required: true
              properties:
                type: string
                attributes:
                  description: Needed because of JSON API
                  type: object
                  required: true
                  properties:
                    name:
                      description: |
                        Name of the custom package to be updated.
                        Note that this attribute can be updated ONLY FOR A CUSTOM PACKAGE.
                      type: string
                      example: My test package
                      required: true
                    contentType:
                      description: |
                        Content type of the custom package to be updated.
                        Note that this attribute can be updated ONLY FOR A CUSTOM PACKAGE.
                      type: string
                      enum: [all, aggregatedfulltext, abstractandindex, ebook, ejournal, print, onlinereference, unknown]
                      example: unknown
                      required: true
                    customCoverage:
                      description: |
                        Coverage dates of the custom or managed package to be updated.
                        Note that this attribute can be updated BOTH FOR CUSTOM PACKAGES AND MANAGED PACKAGES.
                      type: customCoverage
                      required: false
                    isSelected:
                      description: |
                        Selection of the managed or custom package to be updated.
                        Note that selection can be updated for BOTH CUSTOM AND MANAGED PACKAGES.
                        For custom packages, if this is set to false, it deletes the package.
                      type: boolean
                      example: true
                      required: false
                    allowKbToAddTitles:
                      description: |
                        Automatically allow KB to add titles for a managed package.
                        Note that this attribute can be updated ONLY FOR A MANAGED PACKAGE.
                      type: boolean
                      example: true
                      required: false
                    visibilityData:
                      description: |
                        Indicates whether package should be hidden or visible to patrons.
                        Note that this attribute can be updated both for CUSTOM AND MANAGED PACKAGES.
                      type: visibilityData
                      required: false
          example: !include examples/packages/packages_put_request.json
      responses:
        200:
          description: OK
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_put_200_response.json
        400:
          description: Bad Request
          body:
            application/vnd.api+json:
                example: !include examples/packages/packages_packageId_put_400_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_put_404_response.json
        422:
          description: Unprocessable Entity
          body:
            application/vnd.api+json:
              example: !include examples/packages/packages_packageId_put_422_response.json
    delete:
      description: |
        Delete a specific custom package using packageId.
        Note that packageId is providerId-packageId
      responses:
        204:
          description: No Content
    /resources:
      get:
        description: Include all resources belonging to a specific package
        responses:
          200:
            description: OK
            body:
              application/vnd.api+json:
                example: !include examples/packages/packages_packageId_resources_get_200_response.json

/eholdings/providers:
  displayName: Providers
  description: Collection of available providers in eholdings.
  get:
    description: Get a list of providers based on the search field.
    is: [indexable]
    responses:
      200:
        body:
          application/vnd.api+json:
            description: List of providers matching the provider name and the total number of providers found.
            example: !include examples/providers/providers_get_200_response.json
  /{provider_id}:
    description: Entity representing a provider
    get:
      description: Get the provider with providerId = {provider_id}
      queryParameters:
        include:
          displayName: Nested resource
          type: string
          description: Name of nested resource to include
          default: packages
          required: false
      responses:
        200:
          body:
            application/vnd.api+json:
              description: Provider details from EPKB for a specific provider ID.
              example: !include examples/providers/providers_providerId_get_200_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/providers/providers_providerId_404_response.json
    put:
      description: |
        This operation allows you to update provider proxy and token values for a specifix provider ID.
      headers:
        Content-Type:
          example: application/vnd.api+json
      body:
        application/vnd.api+json:
          properties:
            data:
              description: Needed because of JSON API
              type: object
              required: true
              properties:
                type: string
                attributes:
                  description: Needed because of JSON API
                  type: object
                  required: true
                  properties:
                    providerToken:
                      displayName: Provider token
                      type: object
                      description: |
                        Tokens are variables in content URLs that identify the customer.
                        The token is text within the URL that needs to be replaced with an institute-specific value.
                      example: |
                        {
                          "value": "hellotoken"
                        }
                      required: false
                    proxy:
                      displayName: Proxy ID
                      type: proxy
                      required: false
          example: !include examples/providers/providers_providerId_put_request.json
      responses:
        200:
          body:
            application/vnd.api+json:
              description: The server has successfully fulfilled the PUT request.
              example: !include examples/providers/providers_providerId_put_200_response.json
        500:
          body:
            application/vnd.api+json:
              description: Unexpected error.
    /packages:
      get:
        description: |
          This operation allows you to retrieve a list of packages from EPKB for a provider including customer context.
        is: [indexable, filterable]
        responses:
          200:
            description: OK
            body:
              application/vnd.api+json:
                example: !include examples/providers/providers_providerId_packages_get_200_response.json
          400:
            description: Bad Request
            body:
              application/vnd.api+json:
/eholdings/resources:
  displayName: Resources
  post:
    description: Create a relation between an existing custom package and an existing custom/managed title.
    headers:
      Content-Type:
        example: application/vnd.api+json
    body:
      application/vnd.api+json:
        properties:
          data:
            description: Needed because of JSON API
            type: object
            required: true
            properties:
              type: string
              attributes:
                description: Needed because of JSON API
                type: object
                required: true
                properties:
                  packageId:
                    description: |
                      Id of the custom package to which the managed/custom title is to be associated.
                      Note that packageId is a combination of vendorId-packageId.
                    type: string
                    example: 123355-2845510
                    required: true
                  titleId:
                    description: Id of the managed/custom title that needs to be associated to a custom package.
                    type: string
                    example: "17059786"
                    required: true
                  url:
                    description: Custom URL displaying the relationship between the custom package and custom/managed title.
                    type: string
                    required: false
                    example: https://hello.io
        example: !include examples/resources/resources_post_request.json
    responses:
      200:
        description: OK
        body:
          application/vnd.api+json:
            example: !include examples/resources/resources_post_200_response.json
      400:
        description: Bad Request
      422:
        description: Unprocessable Entity
        body:
          application/vnd.api+json:
            example: !include examples/resources/resources_post_422_response.json
  /{resourceId}:
    get:
      description: |
        Retrieve a specific resource given resourceId.
        Note that a resource is a managed/custom title associated with a managed/custom package.
        resourceId is providerId-packageId-titleId
      queryParameters:
        include:
          displayName: Nested provider, package or title
          type: string
          enum: ["provider", "package", "title"]
          description: Include provider, package or title in response
          example: provider
          required: false
      responses:
        200:
          description: OK
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_get_200_response.json
        400:
          description: Bad Request
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_get_404_response.json
    put:
      description: |
        Update a managed or custom resource using resourceId
        Note that resourceId is providerId-packageId-titleId
      headers:
        Content-Type:
          example: application/vnd.api+json
      body:
        application/vnd.api+json:
          properties:
            data:
              description: Needed because of JSON API
              type: object
              required: true
              properties:
                type: string
                attributes:
                  description: Needed because of JSON API
                  type: object
                  required: true
                  properties:
                    url:
                      description: |
                        Custom URL of a custom resource.
                        Note that this attribute can be updated ONLY FOR A CUSTOM RESOURCE.
                      type: string
                      example: "https://hello.io"
                      required: false
                    customCoverages:
                      description: |
                        Coverage dates of the custom or managed resource to be updated.
                        Note that this attribute can be updated BOTH FOR CUSTOM RESOURCES AND MANAGED RESOURCES.
                      type: array
                      items: customCoverage
                      required: false
                      example:
                        - # start item 1
                          beginCoverage: 2018-06-03
                          endCoverage: 2018-06-04
                        - # start item 2
                          beginCoverage: 2018-06-05
                          endCoverage: 2018-06-06
                    isSelected:
                      description: |
                        Selection of the managed or custom resource to be updated.
                        Note that selection can be updated for BOTH CUSTOM AND MANAGED RESOURCES.
                        For custom resources, if this is set to false, it disassociates the resource from the contained custom package.
                        If the title is custom and is not associated with any other package, then the title will be deleted from the knowledge base.
                        This param is required for a custom resource and is optional for a managed resource.
                      type: boolean
                      example: true
                      required: true
                    visibilityData:
                      description: |
                        Indicates whether resource should be hidden or visible to patrons.
                        Note that this attribute can be updated both for CUSTOM AND MANAGED RESOURCES.
                      type: visibilityData
                      required: false
                    coverageStatement:
                      description: |
                        Coverage Statement of a managed or custom resource.
                        Note that this attribute can be updated both for CUSTOM AND MANAGED RESOURCES.
                      type: string
                      required: false
                      example: "Sample coverage statement"
                    customEmbargoPeriod:
                      description: |
                        Custom Embargo of a managed or custom resource.
                        Note that this attribute can be updated both for CUSTOM AND MANAGED RESOURCES.
                      type: customEmbargoPeriod
                      required: false
                    proxy:
                      description: |
                        Ability to update selection of proxy for a custom or managed resource.
                        Note that this attribute can be updated both for CUSTOM AND MANAGED RESOURCES.
                      type: proxy
                      required: false
          example: !include examples/resources/resources_put_request.json
      responses:
        200:
          description: OK
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_put_200_response.json
        400:
          description: Bad Request
          body:
            application/vnd.api+json:
                example: !include examples/resources/resources_resourceId_put_400_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_put_404_response.json
        422:
          description: Unprocessable Entity
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_put_422_response.json
    delete:
      description: |
        Delete the association between a custom/managed title and a custom package using resourceId.
        Note that resourceId is providerId-packageId-titleId
        If the title is custom and is not associated with any other package, then the title will be deleted from the knowledge base.
      responses:
        204:
          description: No Content
        400:
          description: Bad Request
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_delete_400_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/resources/resources_resourceId_delete_404_response.json

/eholdings/titles:
  displayName: Titles
  description: Collection of available titles in eholdings.
  get:
    description: Get a set of titles matching the given search criteria.
    queryParameters:
      q:
        displayName: Query by Title Name
        type: string
        description: String to search title name to get a collection of titles
        example: War and Peace
        required: false
      page:
        displayName: Page offset
        type: integer
        minimum: 1
        maximum: 2147483647
        description: Page offset to retrieve results from Ebsco KB
        example: 1
        required: false
      count:
        displayName: Count
        type: integer
        minimum: 0
        maximum: 100
        description: Count of number of results to retrieve from Ebsco KB
        example: 100
        required: false
      sort:
        displayName: Sort options
        type: string
        enum: ["name", "relevance"]
        description: Option by which results are sorted. Defaults to relevance if query or name if no query.
        example: name
        required: false
      filter[selected]:
        displayName: Selection status
        type: string
        enum: ["true", "false", "ebsco", "all"]
        description: Filter to narrow down results based on selection status. Defaults to all.
        example: "false"
        required: false
      filter[type]:
        displayName: Resource type
        type: string
        enum: ["all", "audiobook", "book", "bookseries", "database", "journal", "newsletter", "newspaper", "proceedings", "report","streamingaudio", "streamingvideo","thesisdissertation",  "website", "unspecified"]
        description: Filter to narrow down results based on resource type. Defaults to all.
        example: book
        required: false
      filter[name]:
        displayName: Query by Title Name
        type: string
        description: String to search title name to get a collection of titles
        example: War and Peace
        required: false
      filter[isxn]:
        displayName: Query by ISSN/ISBN
        type: string
        description: String to search ISSN and ISBN to get a collection of titles
        example: 1050-3331
        required: false
      filter[subject]:
        displayName: Query by Subject
        type: string
        description: String to search subjects to get a collection of titles
        example: history
        required: false
      filter[publisher]:
        displayName: Query by Publisher
        type: string
        description: String to search publishers to get a collection of titles
        example: academic
        required: false
    responses:
      200:
        body:
          application/vnd.api+json:
            description: An array of titles comprising the results of the query.  The array will be paged if its length exceeds the value set with the `count` query param, or the default `count` of 25 in its stead.  The included metadata gives us the total result count outside of the paged context.
            example: !include examples/titles/titles_get_200_response.json
  /{title_id}:
    description: Entity representing a title
    get:
      description: Get the title by its unique identifier.
      queryParameters:
        include:
          displayName: Related Resources
          type: string
          enum: ["resources"]
          description: Include related resource obects, each representing a partnering of this title with a package.  Any bogus value, like `include=deciduousTrees`, will be silently ignored.
          example: "resources"
          required: false
      responses:
        200:
          body:
            application/vnd.api+json:
              description: EPKB data for the title matching {title_id}
              example: !include examples/titles/titles_titleId_get_200_response.json
        404:
          description: Not Found
          body:
            application/vnd.api+json:
              example: !include examples/titles/titles_titleId_get_404_response.json
  post:
    description: Create a new Custom Title.
    headers:
      Content-Type:
        example: application/vnd.api+json
    body:
      application/vnd.api+json:
        properties:
          data:
            description: Needed because of JSON API
            type: object
            required: true
            properties:
              type: string
              attributes:
                description: Needed because of JSON API
                type: object
                required: true
                properties:
                  name:
                    description: |
                      Name of the new title that is to be created.
                    type: string
                    example: "A New Title For You"
                    required: true
                  publicationType:
                    description: Publication type for new title.
                    type: string
                    enum: ["All", "Audiobook", "Book", "Book Series", "Database", "Journal", "Newsletter", "Newspaper", "Proceedings", "Report", "Streaming Audio", "Streaming Video", "Thesis & Dissertation", "Website", "Unspecified"]
                    example: "Book"
                    required: true
          included:
            description: Resource used to create new title.
            type: array
            required: true
            items: includedPackageId
        example: !include examples/titles/titles_post_request.json
    responses:
      200:
        description: OK
        body:
          application/vnd.api+json:
            example: !include examples/titles/titles_post_200_response.json
      400:
        description: Bad