ORCID ma na celu obsługę 2 głównych wersji API jednocześnie. Gdy zostanie wydana nowa główna wersja interfejsu API, ORCID gwarantuje wsparcie przez co najmniej trzy lata od daty premiery. Ponadto dajemy 12-miesięczne powiadomienie przed wycofaniem najstarszej wersji głównej i wysyłamy okresowe e-maile z przypomnieniem do tych członków, którzy nadal z niej korzystają w okresie wypowiedzenia. Nowe wersje główne są wymagane za każdym razem, gdy wprowadzamy istotne zmiany w naszym schemacie metadanych i są one oznaczane przez zwiększenie głównego numeru wersji. ORCID wydaje nową główną wersję API co 2-4 lata.
W wyjątkowych okolicznościach ORCID może rozważyć wydłużenie 12-miesięcznego okresu wycofania, gdy zostanie wydana nowa główna wersja API, ale jest to wymagane ORCID zainwestować dodatkowe środki w prace konserwacyjne, co w konsekwencji wpłynie na inne działania, takie jak nowy rozwój i wsparcie. ORCID zastrzega sobie prawo do pobierania dodatkowych opłat za dalsze korzystanie z wycofanej wersji API po dacie wycofania, aby pomóc zrekompensować poniesione dodatkowe koszty.
ORCID ma politykę stopniowego wycofywania interfejsów API, która pozwala nam rozwijać naszą ofertę interfejsów API i odpowiadać na potrzeby społeczności między głównymi wydaniami. To znaczy że ORCID może wprowadzić nieistotne zmiany w kontrolowanych słownikach i polach metadanych bieżącej wersji interfejsu API.
- Użytkownicy najnowszej wersji API mogą zignorować te zmiany, ale powinni mieć świadomość, że mogą one zostać wprowadzone
- Użytkownicy poprzedniej wersji API nie otrzymają danych, których nie można zamodelować w ich wersji
Przykładem w chwili pisania tego tekstu jest wprowadzenie taksonomii roli kontrybutora CREDIT do interfejsu API w wersji 3.0. Po uruchomieniu integracje v2.x będą powoli tracić widoczność ról współpracowników, ponieważ coraz więcej badaczy i integracji przyjmuje CREDIT. Użytkownicy wersji 2.x się nie zepsują, ale w miarę upływu czasu będą otrzymywać mniej rozbudowane metadane.
Podczas opracowywania nowej głównej wersji interfejsu API jest to normalne ORCID do tworzenia wersji „kandydatów do wydania”. Są one przeznaczone dla integratorów, którzy są w stanie dokonać aktualizacji w odpowiednim czasie po wydaniu pełnej wersji interfejsu API. Oczekiwany czas życia kandydata do wydania to maksymalnie 12 miesięcy od wydania wersji głównej, dla której został opracowany.
Zalecamy integratorom, aby postępowali zgodnie z Zasada solidności (inaczej prawo Postela) przy korzystaniu z ORCID API.
Tło
ORCID powoli ewoluował swoje API od swoich skromnych początków.
API v1.x (Launch ~2012 wraz z rejestrem) próbowało zwrócić wszystkie metadane o badaczach i ich działaniach w jednej odpowiedzi API. Integratorzy musieli zmodyfikować te metadane i odesłać je w całości w celu dodania nowych pozycji lub aktualizacji istniejących. To była rozsądna pierwsza próba, ale nie skalowała się, a dodawanie i aktualizowanie było bolesnym zadaniem. (emerytowany w marcu 2018 r.)
API 2.x (wydany w lutym 2017 r.) podzieliło nasze API na sekcje; prace, afiliacje, finansowanie, biografia itp. Był to duży krok naprzód i umożliwił zarówno nam, jak i naszym klientom znacznie łatwiejsze zarządzanie dużymi dokumentami. Jednak większość naszych słowników walidacyjnych i kontrolowanych była zakodowana na stałe w schemacie, co utrudniało reagowanie na zmiany
API 3.x (wydany w maju 2019 r.) dodał nowe sekcje do rekordu, takie jak zasoby badawcze, uprościł strukturę schematu i udostępnił ORCID z dodatkową elastycznością. Przeniosło większość sprawdzania poprawności ze schematu na nasze serwery, co umożliwiło nam naprawienie problemów i dodanie nowych typów identyfikatorów bez wydawania kolejnych wersji interfejsu API.
Wydanie nowego głównego interfejsu API to ogromne przedsięwzięcie — jego stworzenie wymaga lat pracy programistów, a nasi członkowie potrzebują kolejnych lat, aby zaktualizować swoje integracje. Z tego powodu staramy się ograniczać wprowadzane przez nas zmiany. Są jednak pewne zmiany, które chcielibyśmy wprowadzić, aby jak najlepiej służyć społeczności.
Naszym zadaniem jest ustalenie, kiedy mamy masę krytyczną, aby wydać nową wersję interfejsu API lub opracowanie sposobów aktualizacji naszych istniejących interfejsów API bez przerywania istniejących integracji.