openapi: 3.0.0

info:
  version: 1.0.1
  title: Simplifier.net FHIR Package API
  description: |
    API to find and retrieve all publicly published FHIR packages.
    * Serves all FHIR packages from Simplifier.net, HL7 International and other public feeds
    * For humans there is the [FHIR Registry at registry.fhir.org](https://registry.fhir.org/) for searching the full package library.
    
    Find the documentation for [other Simplifier.net APIs](https://docs.fire.ly/projects/Simplifier/api.html).

servers:
  - url: 'https://packages.simplifier.net/'
  - url: 'https://packages.fhir.org/'
  - url: 'https://packages2.fhir.org/packages/'
  - url: 'https://npm.fhir.org/packages/'

paths:
  /catalog:
    get:
      summary: Search FHIR packages
      description: |
        Search for FHIR packages by name, canonical and other attributes.
        * Can be used for populating intellisense dropdowns for package search.
        * Does not intend to follow NPM in all aspects and adds extra FHIR specific searches, like canonicals and FHIR versions.
        
        Known limitations:
        * Packages from which all versions are marked as `unlisted` are not returned.
        * The attribute names of the return value are documented here as camelCase, but are in fact currently PascalCase.
      parameters:
        - name: name
          description: Search by (part of) a package name
          in: query
          schema:
            type: string
          examples: 
            hl7.fhir.us.core:
              value: hl7.fhir.us.core
              summary: Full package name
            hl7.fhir:
              value: hl7.fhir
              summary: Partial package name
        - name: version
          description: Search for packages with a version containing this term
          in: query
          schema:
            type: string
          examples:
            4.1.0:
              value: 4.1.0
              summary: Full semver package version
            4.0:
              value: 4.0
              summary: Partial semver package version
        - name: canonical
          description: Search for packages or resource contained in it with this term in their canonical
          in: query
          schema:
            type: string
          examples:
            full-canonical:
              value: http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
              summary: Full canonical
            partial-canonical:
              value: http://hl7.org/fhir/
              summary: Partial canonical
        - name: pkgcanonical
          description: Search for packages with this exact canonical
          in: query
          schema:
            type: string
          example: http://hl7.org/fhir/us/core
        - name: fhirVersion
          description: Limit search by FHIR version
          in: query
          schema:
            type: string
            enum:
              - R2
              - R3
              - R4
              - R4B
              - R5
        - name: prerelease
          description: Whether to include or exclude prerelease package versions
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A list of package objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageList'
        '404':
          description: No packages found for the package name
        
  /{package-name}:
    get:
      summary: List package versions.
      description: |
        Endpoint to retrieve all versions for a package name.
        * The payload is compliant with the NPM package version listing.
        * The `dist-tags` element will provide tags on certain versions, like the label of which version is the `latest`.
        * In calculating `latest` the highest stable semver version is used, not the most recently published version.
        * If an author has indicated that the package should no longer be used, the element `unlisted` will be populated for a version.
      parameters:
        - name: package-name
          in: path
          description: Name of the package
          required: true
          schema:
            type: string
          example: hl7.fhir.us.core
      responses:
        '200':
          description: A package object with all available versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersionsObject'
        '404':
          description: No packages found for the package name
        
  /{package-name}/{package-version}:
    get:
      summary: Download package version
      description: |
        Download a specific package version.
      parameters:
        - name: package-name
          in: path
          description: Name of the package
          required: true
          schema:
            type: string
          example: hl7.fhir.us.core
        - name: package-version
          in: path
          description: Version of the package
          required: true
          schema:
            type: string
          example: 3.1.1
      responses:
        '200':
          description: A package object with all available versions
          content:
            application/tar+gzip:
              schema:
                type: string
                format: binary
        '404':
          description: No packages found for the package name or version

components:
  schemas:
    PackageVersionsObject:
      description: An object listing package metadata and all individual versions
      properties:
        _id:
          description: Package Id
          type: string
          example: hl7.fhir.us.core
        name:
          description: Package name
          type: string
          example: hl7.fhir.us.core
        dist-tags:
          title: Distribution tags
          description: Tags describing specific package versions
          type: object
          properties:
            latest:
              title: latest
              description: A pointer to the latest package version
              type: string
              example: 1.0.0
        versions:
          title: Package versions
          description: Dictionary object of package versions
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PackageVersion'
            
    PackageList:
      description: A list of Package objects
      type: array
      items:
        $ref: '#/components/schemas/Package'
        
    PackageVersion:
      description: An object describing a specific version of a package
      allOf:
      - $ref: '#/components/schemas/Package'
      - type: object
        properties:
          version:
            type: string
            description: Package version
            example: 1.0.0
          dist:
            type: object
            properties:
              shasum:
                type: string
                example: 8dd6ac852c1d2cb4ac7312188d8d6ef7ccb65da6
              tarball:
                type: string
                example: https://packages.simplifier.net/hl7.fhir.us.core/1.0.0
          url:
            type: string
            description: Url for downloading this package
            example: https://packages.simplifier.net/hl7.fhir.us.core/1.0.0
            
    Package:
      description: An object describing a package
      properties:
        name:
          type: string
          description: Package name
          example: hl7.fhir.us.core
        description:
          type: string
          description: Package description
          example: "The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Common Clinical Data Set (CCDS), and ONC U.S. Core Data for Interoperability (USCDI) v1 provided the requirements for this guide."
        fhirVersion:
          type: string
          description: Package FHIR version
          example: R4