openapi: 3.2.0
info:
  title: University of Florida Libraries Patron Discovery API
  version: '2026-09-01'
  summary: Public, unauthenticated read API over the University of Florida Digital Collections, the Digital Library of the Caribbean and the Florida Digital Newspaper Library.
  description: '`api.patron.uflib.ufl.edu` is the backend of the UF Digital Collections reader at

    ufdc.ufl.edu.'
  contact:
    name: UF Digital Library Center
    email: digby@ufl.edu
    url: https://lts.uflib.ufl.edu/supported-systems/uf-digital-collections/
  x-operator: institution
  x-operator-basis: api.patron.uflib.ufl.edu -> 128.227.18.113, 128.227.24.223; ARIN NetName UFNET, OrgName "University of Florida", CIDR 128.227.0.0/16. No vendor CNAME. TLS issuer "C=US, O=Internet2, CN=InCommon RSA Server CA 2". The OAI-PMH Identify response names UF as the repository and digby@ufl.edu as adminEmail. No vendor product string appears in any probed response.
  x-provenance:
    generated: '2026-09-01'
    method: derived
    source: Live HTTP probes of every resource named in the root index of https://api.patron.uflib.ufl.edu on 2026-09-01, plus the self-documenting example URLs each resource root returns. The host itself was discovered by reading https://ufdc.ufl.edu/assets/environment-CtcEkdJa.js, the UFDC client's build-time environment module.
servers:
- url: https://api.patron.uflib.ufl.edu
  description: 'Production. Public and unauthenticated; no API key is issued or required.


    WARNING — the hostname resolves to TWO A records that do not serve the same routes.

    128.227.18.113 serves every resource. 128.227.24.223 serves every resource EXCEPT

    /oai and /oai_by_title, which it returns 404 for. Verified 2026-09-01 by pinning

    each address with --resolve and replaying all nine sampled routes against both. See

    `x-node-divergence`.'
tags:
- name: Discovery
  description: Root index and controlled vocabularies.
paths:
  /:
    get:
      tags:
      - Discovery
      operationId: getRootIndex
      summary: Machine-readable index of every resource
      description: Returns a flat object mapping resource name to absolute URL. Seventeen resources observed on 2026-09-01.
      responses:
        '200':
          description: Resource index.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  format: uri
  /collections:
    get:
      tags:
      - Discovery
      operationId: listCollections
      summary: List collections, or one collection
      parameters:
      - name: coll
        in: query
        description: '`all` for every collection, or a collection code such as `maps` or `aerials`.'
        schema:
          type: string
      responses:
        '200':
          description: Collection descriptions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
  /types:
    get:
      tags:
      - Discovery
      operationId: listTypes
      summary: Media types with live item counts
      responses:
        '200':
          description: Media types.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountedFacet'
  /publishers:
    get:
      tags:
      - Discovery
      operationId: listPublishers
      summary: Publishers with live item counts
      responses:
        '200':
          description: Publishers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountedFacet'
  /recent_additions:
    get:
      tags:
      - Discovery
      operationId: getRecentAdditions
      summary: Most recently published items
      responses:
        '200':
          description: Recent items, same hit shape as search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /fdnl_titles_list:
    get:
      tags:
      - Discovery
      operationId: listFdnlTitles
      summary: Florida Digital Newspaper Library title list
      description: Every FDNL newspaper title with its county and geographic coordinates. Effectively an open dataset of Florida newspaper publishing history.
      responses:
        '200':
          description: FDNL titles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FdnlTitle'
components:
  schemas:
    Collection:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        shortname:
          type: string
        description:
          type: string
          description: HTML.
    FdnlTitle:
      type: object
      properties:
        bibid:
          type: string
        vid:
          type: string
        title:
          type: string
        coordinates:
          type: array
          items:
            type: string
            description: '"lat,lng".'
        county:
          type: string
        vids_per_bibid:
          type: integer
        min_date:
          type:
          - string
          - 'null'
        max_date:
          type:
          - string
          - 'null'
    CountedFacet:
      type: object
      properties:
        name:
          type: string
        current_item_count:
          type: integer
        es_keyword:
          type: string
          description: Underlying search-index keyword.
    Hit:
      type: object
      properties:
        did:
          type: string
          description: '`BIBID:VID`.'
        bibid:
          type: string
        vid:
          type: string
        title:
          type: string
        mediatype:
          type: string
        aggregationcodes:
          type: array
          items:
            type: string
        mainthumbnail:
          type: string
        mainjpeg:
          type: string
        pagecount:
          type: integer
        language:
          type: array
          items:
            type: string
        creator:
          type: array
          items:
            type: string
        subject_keyword:
          type: array
          items:
            type: string
        genre:
          type: array
          items:
            type: string
        source_institution:
          type: string
        holding_location:
          type: string
        publication_date:
          type: string
        conv_date:
          type: string
          description: Normalised date, YYYY-MM-DD.
        collections:
          type: array
          items:
            type: string
        general_note:
          type: array
          items:
            type: string
        ip_restriction_mask:
          type:
          - integer
          - string
        made_public_date:
          type: string
        hit_reason:
          type:
          - string
          - array
          - object
    SearchResult:
      type: object
      required:
      - hits
      properties:
        query:
          type:
          - string
          - object
        hit_count:
          type: integer
        filter_buckets:
          type: object
          description: Facet counts keyed by field.
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
        ip:
          type: string
          description: The API echoes the CALLER's own IP address back in this field. It is not institutional data and must not be stored in a catalogued example.
x-node-divergence:
  observed: '2026-09-01'
  method: probed
  hosts:
  - address: 128.227.18.113
    routes_ok: all sampled
  - address: 128.227.24.223
    routes_404:
    - /oai
    - /oai_by_title
    routes_ok:
    - /
    - /types
    - /exactsearch
    - /recent_additions
    - /rss_ufdc
    - /collections
    - /fdnl_titles_list
  impact: An OAI-PMH harvester that resolves onto the second node receives HTTP 404 and concludes the repository has been withdrawn. Which node answers is a DNS ordering accident, so the failure is intermittent and will not reproduce on a retry that lands on the other address. This is deployment drift between two backends, not a deliberate partition — every other route is served identically by both.