id: https://nde.nl/ontology/hc/class/SearchAPI
name: search_api
title: SearchAPI Class
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  dcat: http://www.w3.org/ns/dcat#
  dcterms: http://purl.org/dc/terms/
  schema: http://schema.org/
  hydra: http://www.w3.org/ns/hydra/core#
  xsd: http://www.w3.org/2001/XMLSchema#
imports:
  - linkml:types
  - ../enums/HTTPMethodEnum
  - ../enums/PaginationMethodEnum
  - ../enums/SearchResponseFormatEnum
  - ../metadata
  - ../slots/has_score
  - ../slots/has_format
classes:
  SearchAPI:
    is_a: DataServiceEndpoint
    class_uri: hc:SearchAPI
    description: "REST/JSON search API endpoint for heritage collection discovery.\n\
      \n**Purpose:**\n\nModels search APIs that provide programmatic access to collection\
      \ search\nfunctionality. These APIs enable:\n- Custom search interface development\n\
      - Integration with aggregation platforms\n- Automated data discovery\n- Faceted\
      \ search and filtering\n\n**Common Patterns:**\n\nHeritage search APIs typically\
      \ support:\n- **Full-text search**: Query across all fields\n- **Field-specific\
      \ search**: Query specific metadata fields\n- **Faceted search**: Filter by\
      \ category, date, type, etc.\n- **Pagination**: Navigate large result sets\n\
      - **Sorting**: Order results by relevance, date, etc.\n\n**Example - Nationaal\
      \ Archief Search API:**\n\n```yaml\nsearch_api:\n  endpoint_name: \"Nationaal\
      \ Archief Search API\"\n  endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/api/zoeken\"\
      \n  protocol: REST\n  query_parameters:\n    - name: \"q\"\n      type: \"string\"\
      \n      description: \"Full-text search query\"\n    - name: \"from\"\n    \
      \  type: \"integer\"\n      description: \"Pagination offset\"\n    - name:\
      \ \"size\"\n      type: \"integer\"\n      description: \"Results per page\"\
      \n  pagination_method: OFFSET_LIMIT\n  max_results_per_page: 100\n  response_format:\
      \ JSON\n  supports_facets: true\n  facet_fields: [\"type\", \"periode\", \"\
      archief\"]\n```\n\n**Response Structure:**\n\nMost heritage search APIs return\
      \ JSON with:\n- `total`: Total number of matching records\n- `results`/`items`/`records`:\
      \ Array of result objects\n- `facets`: Aggregation counts for filtering\n- `pagination`:\
      \ Links or cursors for paging\n\n**See Also:**\n\n- OpenSearch: https://opensearch.org/\n\
      - Hydra API vocabulary: https://www.hydra-cg.com/\n"
    comments:
    - Primary interface for programmatic collection discovery
    - Most heritage institutions expose REST/JSON search APIs
    - Consider rate limits and pagination for large-scale harvesting
    see_also:
    - https://opensearch.org/
    - https://www.hydra-cg.com/spec/latest/core/
    slots:
    - has_score
    - has_url
    - has_format
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: '[''*'']'
  SearchQueryParameter:
    class_uri: hydra:IriTemplateMapping
    description: 'Describes a query parameter supported by a search API.


      Documents the parameter name, type, whether it''s required,

      and its purpose.

      '
    slots:
    - has_score
    - has_name