Skip to content

ADR - Deprecate current set of APIs and create new set which works from (dynamic) source of Reference data - per Geomatics team's recommendation

Status

  • Proposed
  • Trialing
  • Under review
  • Approved
  • Retired

Context

Recent discussions involving Geomatics team, PMC and EA members. One of them being on 9-Mar-2022 (see attachment, slide-3).

OSDU_Geomatics_for_meeting_23-09-21_with_EA_team__002_.pdf

There are two parts in this ADR :

  1. Deprecate (over time) currently available set of "CRS Catalog" APIs
  2. Design specification and implement new set of APIs

Do not expect to find detailed design specification of new APIs here as they will be created separately.

This issue is simply to initiate discussion for decision so that real work can start.

Task-2 will be done by Geomatics SMEs (@bert.kampes , @sigridmatthes , Phil (phil.summerfield@exxonmobil.com), Jin Zhu (jin.zhu@chevron.com) , @josh.townsend et al) and @gehrmann of "Data Definition" team in collaboration with Developer resources (assigned from AWS).

AWS contact is @fhoueto.amz

You can find historical context in the following issues:

  • APIs need to retrieve values from Reference data CoordinateReferenceSystem and CoordinateTransformation (#6 (closed))
  • Need simple mechanism to perform regional search, with further filtering (#9 (closed))
  • more will be added here

Scope

Provide enough contextual information here for the Decision makers to agree (or disagree) about deprecating current set of APIs and building a new set of APIs to effectively perform "CRS Catalog" functions from dynamic source.

Decision

EA team may review "pros and cons", risks and provide decision (with approval or otherwise) -

  1. Deprecate (over time - perhaps 6-9 months to play safe) currently available set of "CRS Catalog" APIs
  2. Design specification and implement new set of APIs

Rationale

Why do we need to deprecate current set of APIs and not attempt to fix? Current set of "CRS Catalog" APIs are sourcing information from a static file and are completely disconnected from the true/dynamic source (Reference data).

The catalog is using a different data model that we don’t use with the legacy data. That is why it is a dead end.

Why do we need to build new set of APis? Instead of taking the band-aid approach of "making the old set of APis work off new dynamic source", Geomatics team SMEs thought it is better approach to build new end-points that make more sense at the same time of switching source (from static to dynamic).

Why we cannot simply get by with complex/advanced search? One reason being this will be "tall" ask for end users to figure out very complex search syntax in Lucen for Elasticsearch.

The envisioned end points are not just things that can be accomplished by a single complex call the ordinary search. It may be it takes 2 calls for example to accomplish fetching a list of CRS to associated with ingested data (i.e., fetch all boundCRSs and then augment that with a fetched list of WGS 84 based CRSs (because they are not considered of type bound in OSDU).

Another example is dealing with the antimeridian for area search may not be possible with direct search but the Catalog service will enable this convenient way for programmers to use when developing applications using this service.

Consequences

  • Alert community about upcoming deprecation of existing API services (in case someone is using these in their applications).
  • Make suitable documentation and socialize widely new set of APIs
Edited by Bert Kampes