Categorise FHIR restful APIs

Hi All,

Currently we are planning to come up with FHIR APIs which allows to carry out CRUD , search , etc operations . I would like to know how to categories these APIs ? I do not want to have flat list of APIs . One option could be

  1. Resource Instance APIs
    Create, Update , Delete , Read , Version read , Patch , etc

  2. System APIs
    Search , Capability Statement

Plan to represent these API’s using swagger .

Any other options can someone suggest ?

Best Regards,

Can you explain what you mean by “categorization”? Servers are expected to expose their CapabilityStatement at all endpoints. While it’s possible to separate the endpoints that provide search and CRUD operations, typically a single endpoint does everything.

Would like to do logical separation of the API’s and this is what i mean categorization from system level to instance level .

Not sure what you mean by system vs. instance level. Query can happen at the system vs. resource vs. instance level, but that’s already handled by FHIR URL convention. Can you explain in more detail (with examples) what you’re trying to do and explain why?

As Lloyd called out, I don’t understand what you’re trying to from a categorization perspective. Personally, I think the categorization on the Resource List page ( is pretty good. From a Swagger / Open API Spec perspective, we’ve tried to have one spec file per resource. Just be aware that some of the things done in FHIR don’t lend themselves nicely to JSON Schema that is used within Open API Spec. Personally, I’d rather see people going to the HL7 FHIR site to understand how to use it, and then only complementing that documentation with things that might be specific to your implementation (e.g. are there properties on a given resource that you will always return, even though the spec allows them to be optional).

1 Like