Duplication of resource data across APIs

[JDMKSZ]

In which measure should duplication of resources across APIs be avoided ?

• for dynamic resources: APIs may/may not add data retrieved from an external API like a person's given name, family name retrieved from national registry
• for code lists (refData): many APIs reuse common ref data or code lists like gender code, marital status, countries

Considerations:

• BFF (backend for front-end) pattern tend to combine different data sources tailor-made for a single front-end, with performance benefits (like caching)
• reusable APIs that group or aggregate data from many sources for use in a specific business case (e.g. dimona declaration or presence registrations)
• back-office APIs exposing an authentic source often limit to just identifiers from external resources, to avoid cascade of changes in the resource's representation

---

Original issue opener

When using IDs that belong to another API, it is not recommended to include the links to the resources in an response (because the path can change, ...). I don't find this recommendation in the guide.

Aside from that, could we add some recommendations on when refData can be used? Or more in general aboud "enrichment", as I would call it?

Take for example Belgian addresses. An authentic source exists for those. Should API's just return the BeST ID? Or can they return the address in String format too (in all the available languages)?

Same question goes for CBE organizations. There's an authentic source, but the list is semi-static. Could they be in a refData?

A similar question for countries. If I just use the NIS-code or ISO-code in my response, can I link to the refData for the available countries with their translations and validation periods? Or should I refer in my documentation to the CountryServices instead, which serve as the authentic source of the NIS-codes? For ISO-codes, one could even refer to the official standard.

Then a slightly different case. Rule [prb-type] allows us to define problem types in /refData/problemTypes. Can these be generalized in a generic API for our organization, in a different location? How to refer to it?

[pvdbosch]

When using IDs that belong to another API, it is not recommended to include the links to the resources in an response (because the path can change, ...). I don't find this recommendation in the guide.

It's been added to the latest version of the guide in [hyp-links], after discussion in #101

It is NOT RECOMMENDED to link to resources in other APIs to avoid a tight coupling between the APIs, unless the link target is guaranteed to remain very stable (like the href links to standard problem types [err-problem])

About:

Can these be generalized in a generic API for our organization, in a different location? How to refer to it?

I think this would be a good way to do this. This can fall under the "...unless the link target is guaranteed to remain very stable" exception of the above rule.

On the general question about enrichment (inline, refdata, embedding, no enrichment at all, ...), we didn't come to a general guideline in #101 because there are many different use cases requiring different solutions. We probably could at most include some design considerations like performance (caching/embedding), complexity of client software, data quality, ...

[JDMKSZ]

It's been added to the latest version of the guide in [hyp-links], after discussion in https://github.com/belgif/rest-guide/issues/101 Thanks (I didn't find it when searching for "external")

We probably could at most include some design considerations like performance (caching/embedding), complexity of client software, data quality, ... I think we should add some rules of thumb though, e.g.:

• You SHOULD NOT add (external) resources as refData. E.g. a payment method, delivery status or marital status is often an enumeration of which the scope is local to the API. An exhaustive list of countries or CBE numbers is not.
• Try to minimize the embedding of data of other resources. For example, in a tax API, a taxpayer (person) should be identified by its person number (SSIN) only. It's often desirable to add maybe a name, first name and birth date, but try to minimize these data as they're present in a different (external) API.

[pvdbosch]

Updated the issue description to limit the scope to duplication of resource data across APIs (the linking issue has been addressed).

IMO this is an architecture decision for which we might only recommend to take into account the intended use of the API (see 'considerations' in issue opener).

CBSS' APIs probably fall under the "back-office / authentic source" category.