openapi: 3.0.2
info:
  version: 1.0.6
  title: WorldCat Entity Data Bibliographic Resources Member Enabled Providers API
  description: WorldCat Entity Data
servers:
- url: https://id.oclc.org/worldcat
  description: PROD
tags:
- name: Member Enabled Providers
paths:
  /rest/providers/search:
    get:
      tags:
      - Member Enabled Providers
      summary: Find member enabled providers in the WorldCat Knowledge base
      description: Given metadata find providers enabled by member library
      operationId: find-kb-providers
      parameters:
      - name: alt
        in: query
        description: Format to return results in. application/xml or application/json
        schema:
          type: string
          default: xml
          enum:
          - xml
          - json
        required: false
      - name: q
        in: query
        description: Keyword query to search by
        required: false
        schema:
          type: string
        example: Nature Publishing Group
      - name: title
        in: query
        description: Search by title
        required: false
        schema:
          type: string
        examples:
          keyword:
            value: Nature
          exact-match:
            value: Nature
          starts-with:
            value: Nature%
      - name: provider_uid
        in: query
        description: Identifier of the provider associated with the collection
        required: false
        schema:
          type: string
        example: NPG
      - name: startIndex
        in: query
        description: start position of the results to return (1 based), default 1
        required: false
        schema:
          type: integer
          format: int32
          default: 1
        example: 10
      - name: itemsPerPage
        in: query
        description: maximum number of records to return, maximum 50, default 10
        required: false
        schema:
          type: integer
          format: int32
          default: 10
        example: 50
      - name: orderBy
        in: query
        description: Criteria for sorting the results. possible sorting criteria are title, relevancy, holdings, preference, issn, isbn, oclcnum
        required: false
        schema:
          type: string
          default: title asc
        example: relevancy
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderSearchResults'
              examples:
                success-search-collection:
                  $ref: '#/components/examples/success-search-provider'
        '400':
          description: Invalid query. The request was unacceptable, often due to missing a required parameter.
          content:
            application/json:
              schema:
                type: object
              examples:
                missing-query-parameter:
                  $ref: '#/components/examples/missing-query-parameter'
        '405':
          description: Method not supported, see response Allow header
          content:
            application/json:
              schema:
                type: object
              example:
                summary: Error when invalid HTTP method used
                value:
                  title: NOT_ALLOWED
                  detail: POST method not allowed
        '500':
          description: Something went wrong (hopfully rare) - please try again
          content:
            application/json:
              schema:
                type: object
      security:
      - api_key: []
  /rest/providers/{provider_ID}:
    get:
      tags:
      - Member Enabled Providers
      summary: Read member enabled providers in the WorldCat Knowledge base by ID
      description: Given metadata find providers enabled by member library
      operationId: read-kb-provider
      parameters:
      - name: alt
        in: query
        description: Format to return results in. application/xml or application/json
        schema:
          type: string
          default: xml
          enum:
          - xml
          - json
        required: false
      - name: provider_ID
        in: path
        description: Identifier of the collection
        required: true
        schema:
          type: string
        example: NPG.journals
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
              examples:
                success-read-collection:
                  $ref: '#/components/examples/success-read-provider'
        '400':
          description: Invalid query. The request was unacceptable, often due to missing a required parameter.
          content:
            application/json:
              schema:
                type: object
              examples:
                missing-query-parameter:
                  $ref: '#/components/examples/missing-query-parameter'
        '405':
          description: Method not supported, see response Allow header
          content:
            application/json:
              schema:
                type: object
              example:
                summary: Error when invalid HTTP method used
                value:
                  title: NOT_ALLOWED
                  detail: POST method not allowed
        '500':
          description: Something went wrong (hopfully rare) - please try again
          content:
            application/json:
              schema:
                type: object
      security:
      - api_key: []
components:
  examples:
    success-read-provider:
      summary: successful request to read a provider
      value:
        title: Nature Publishing Group
        id: http://worldcat.org/webservices/kb/rest/providers/NPG
        links:
        - href: http://worldcat.org/webservices/kb/rest/providers/NPG
          rel: self
        - href: http://www.nature.com
          rel: via
        - href: http://worldcat.org/webservices/kb/rest/providers/NPG.html
          rel: alternate
        provider_uid: NPG
        vic_id: 572cde9e-0a1d-40ce-9f54-ad3ffcf42aa6
        provider_name: Nature Publishing Group
        available_collections: '22'
        selected_collections: '22'
        available_entries: '1115'
        selected_entries: '1115'
    success-search-provider:
      summary: successful search of providers
      value:
        title: 'WorldCat KnowledgeBase Search: Nature'
        updated: '2020-01-07T21:36:44.887Z'
        id: urn:uuid:ca4e882b66bd43d6cc0c885337971941
        author: OCLC
        links:
        - href: http://worldcat.org/webservices/kb/rest/providers/search?q=Nature&startIndex=1&search-type=search&itemsPerPage=10&scope=my&orderBy=title+asc&institution_id=128807
          rel: self
        os:totalResults: '1'
        os:startIndex: '1'
        os:itemsPerPage: '10'
        os:Query: q=Nature&startIndex=1&search-type=search&itemsPerPage=10&scope=my&orderBy=title+asc&institution_id=128807
        entries:
        - title: Nature Publishing Group
          id: http://worldcat.org/webservices/kb/rest/providers/NPG,128807
          links:
          - href: http://worldcat.org/webservices/kb/rest/providers/NPG,128807
            rel: self
          - href: http://www.nature.com
            rel: via
          - href: http://worldcat.org/webservices/kb/rest/providers/NPG,128807.html
            rel: alternate
          kb:provider_uid: NPG
          kb:vic_id: 572cde9e-0a1d-40ce-9f54-ad3ffcf42aa6
          kb:provider_name: Nature Publishing Group
          kb:available_collections: '19'
          kb:selected_collections: '1'
          kb:available_entries: '980'
          kb:selected_entries: '105'
    missing-query-parameter:
      summary: Error returned when required query parameter not sent
      value:
        type: MISSING_QUERY_PARAMETER
        title: Validation Failure
        detail: Required String parameter 'q' is not present
  schemas:
    ProviderSearchResults:
      type: object
      properties:
        title:
          description: name of the results
          type: string
        updated:
          description: date query run
          type: string
        id:
          description: ID for result set
          type: string
        author:
          description: who created the result set
          type: string
        links:
          description: Link to the results
          type: string
        totalResults:
          description: Total number of results
          type: integer
          format: int32
        startIndex:
          description: start position of the results
          type: integer
          format: int32
        itemsPerPage:
          description: number of items per page
          type: integer
          format: int32
        Query:
          description: query sent to API
          type: string
        entries:
          description: actual results
          type: array
          items:
            $ref: '#/components/schemas/Provider'
    Link:
      type: object
      properties:
        href:
          type: string
        rel:
          type: string
          enum:
          - self
          - alternate
          - parent
          - enclosure
          - via
    Provider:
      type: object
      required:
      - title
      - id
      - links
      - provider_uid
      - provider_name
      - available_collections
      - selected_collection
      - available_entries
      - selected_entries
      properties:
        title:
          description: Name of Provider
          type: string
        id:
          description: URL for Provider in API
          type: string
        links:
          description: links associated with Provider
          type: array
          items:
            $ref: '#/components/schemas/Link'
        provider_uid:
          description: Id for provider
          type: string
        provider_name:
          description: name for provider
          type: string
        vic_id:
          description: id for provider in vendor information center
          type: string
        available_collections:
          description: number of available collection associated with provider
          type: integer
          format: int32
        selected_collection:
          description: Number of collections from provider selected by institution
          type: integer
          format: int32
        available_entries:
          description: Number of available titles from provider
          type: integer
          format: int32
        selected_entries:
          description: Number of selected titles from provider selected by institution
          type: integer
          format: int32
  securitySchemes:
    entity_data_auth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth.oclc.org/token
          scopes:
            publicEntities:read_brief_entities: read brief entity data
            publicEntities:read_references: read entity references
        authorizationCode:
          authorizationUrl: https://oauth.oclc.org/auth
          tokenUrl: https://oauth.oclc.org/token
          scopes:
            publicEntities:read_brief_entities: read brief entity data
            publicEntities:read_references: read entity references