Retrieving related data

Endpoints SHOULD return only primary resources by default.

To prevent overloading clients, the server MAY offer alternative endpoints to fetch related data.

URLs SHOULD NOT exceed two levels of nesting to maintain readability and usability.

If a resource can be independently accessed without its parent, it SHOULD have its own top-level endpoint.

Examples of good practice

{base}/appointmentsService/patients

{base}/appointmentsService/patients/{id}

{base}/appointmentsService/patients/{id}/conditions

{base}/appointmentsService/patients/{id}/conditions/{id}

{base}*/appointmentsService/patients/*{id}*/encounters/*{id}*/observations/*{id}

The server MAY support include and expand query parameters to optimise data retrieval.

include MUST return navigation links for the specified related resources.

expand MUST embed related data directly within the response.

Examples of good practice

{base}/appointmentsService/patients/{id}?include=conditions

{base}/appointmentsService/patients/{id}?expand=practitioners,conditions

Additional RECOMMENDATIONS:

Separate URLs vs Query Parameters: Use query parameters only when they add value. For complex data retrieval, consider GraphQL.
Balance Performance and Usability: Overuse of expand can degrade performance, while excessive nesting complicates API navigation.

Using separate urls for related resources