API Evangelist enhancements for Medplum FHIR API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Medplum FHIR API
  version: 1.0.0
extends: openapi/medplum-fhir-api-openapi.yml
actions:
  - target: $.info
    update:
      x-apievangelist-rating: 4
      x-apievangelist-notes: >-
        Medplum's own OpenAPI (https://api.medplum.com/openapi.json, saved verbatim 2026-10-11) models the
        generic FHIR R4 REST path templates with eleven operations: batch/transaction, search,
        createResource (conditional create via If-None-Exist), conditionalUpdate (upsert, 200/201/412),
        validateResource ($validate), readResource, updateResource, patchResource, deleteResource,
        readResourceHistory and readVersion, with 400/412 responses and OAuth2 / OpenID Connect
        securitySchemes. Per-resource shapes live in the FHIR R4 component schemas; the server's
        CapabilityStatement is saved at fhir/medplum-fhir-r4-capabilitystatement.json.
  - target: $.paths['/fhir/R4/{resourceType}'].get
    update:
      tags:
        - Fhir
        - Search
      x-apievangelist-conventions: conventions/medplum-conventions.yml
  - target: $.paths['/fhir/R4/{resourceType}'].post
    update:
      tags:
        - Fhir
        - Create
      x-apievangelist-idempotency: >-
        Conditional create via the ifNoneExist parameter (FHIR standard) makes createResource
        safely retryable. See conventions/medplum-conventions.yml.
  - target: $.paths['/fhir/R4/{resourceType}/{id}'].put
    update:
      tags:
        - Fhir
        - Update
      x-apievangelist-idempotency: >-
        updateResource (HTTP PUT with a known id) is naturally idempotent — repeating the same
        request with the same body produces the same resulting resource state.
  - target: $.components.securitySchemes
    update:
      x-apievangelist-note: >-
        The spec declares BasicAuth, BearerAuth, and openIdConnect, but Medplum's real production
        auth surface is OAuth 2.0 / SMART App Launch 2.0.0 (confirmed live at
        /.well-known/oauth-authorization-server). See authentication/medplum-authentication.yml
        and scopes/medplum-scopes.yml for the fuller picture the raw securitySchemes block omits.