Automating API style guides / linting with Spectral for FHIR

General enquiries
1

Hi all,

Thanks @tony.heap for the link to here.

I wanted to ask if anyone was building / has built a spectral ruleset for FHIR APIs. We have a reasonable ruleset for our non health APIs but some of the rules are not compatible with FHIR - for example we use kebab case resources “https://api…/v1/sales-orders” instead of /Patient for example.

It would be great to connect with others who care about API standardisation and developer experience.

2

Hi Alex,
At NHS Digital, we have style guides and checklists that are provided as part of the Onboarding Service for API developers, and we align with the FHIR guidelines Http - FHIR v4.3.0
Currently we do not have any linting / Spectral rulesets, but we would be very interested should someone wish to develop some spectral rulesets for FHIR APIs.

3

Thanks for the speedy reply Paul. We have some security related rules and quality ones such as limit your arrays, integers numbers etc. There are a few casing ones which are not compatible atm. I would be happy to share what we have if it would be of interest. I have a team working on something which takes the custom rules and deactivates those that are incompatible with FHIR and replaces with some PascalCase ones instead. Let me know

5

Would you mind expanding on what you are trying to achieve?

Are you trying to describe the FHIR Schema or a FHIR API. Suspect it is both.

As a supplier I roughly the following

  • Create an OAS spec to describe the interactions (this includes examples)
  • (Re)Use a FHIR Implementation Guide. Key points/differences probably go in the OAS spec or word/google doc. I don’t attempt to describe the FHIR schema
  • Stand up a /metadata endpoint, this is mostly for technical purposes. e.g. my healthcheck is AWS ECS uses this endpoint and I also use it to autogenerate first draft of my OAS.
6

Hi Kevin,

FHIR has certain naming and casing requirements which I would like to automatically assist designers to be compliant with using a Linter (Spectral Spectral - Open Source API Description Linter | Stoplight | Stoplight). Its one less thing to think about / be distracted by when you are focused on delivering value.

7

Ah ok.

I just tend to stick with FHIR code libraries Open Source Implementations - FHIR - Confluence
So I don’t really come across that issue.

8

Thanks for the reply on this. I wonder if there are others doing API Design first with OpenAPI3 and how they are ensuring the definitions are compliant with FHIR> thats what we are trying to achieve here.

9

I’ve had a brief look to see what was possible.

The method I tried was to take a OAS/swagger spec and check the resource names were correct (this is in a FHIR ValueSet). I was then checking the parameters against FHIR SearchParameters (I think these were in a download).

In theory I think I could then call those API’s with a FHIR Client to check the API functions correctly.

This approach would also work against a FHIR CapabilityStatement if you chose to document the API that way.

10

100%. Spectral helps ensure the design is compliant. then you can feed that OpenAPI into a contract tester and use the real API. It should help to get APIs right first time and with high quality documentation to boot.

11

Hi! Out curiosity? Were you able to gain traction on this topic? Developing and/or finding information on how to follow API first design principle for creating a FHIR Style API?

12

Sadly not. I also enquired about in the API community - APIsYouWontHate but no luck there either :frowning: