OneRoster 명단은 파일로 넘기거나 API로 조회한다

명단을 옆 시스템에 넘기는 방법은 둘이다.

하나는 적어서 건네는 것, 하나는 물어보게 하는 것이다.

건넨 명단은 건넨 때가 최신이고, 물어본 명단은 물어본 때가 최신이다.

그래서 “지금 몇 명인가”에 두 방식이 다르게 답한다.

여기까지가 핵심이다

여기서부터는 위 두 줄을 표준의 말로 다시 적는다. 이 글의 범위는 명단을 언제 어떤 모양으로 건네는가이다. 명단 한 줄이 무엇인지는 OneRoster는 누가 그 반인지를 넘긴다에, 그 줄에서 사람을 무엇으로 가리키는지는 OneRoster는 사람을 번호로 가리킨다에 두었다.

3월 2일에 명단을 넘겼고, 3월 5일에 전입생이 들어왔다. 학습 화면은 며칠째 27명을 보여 준다. 명단이 틀린 것이 아니다. 3월 2일 이후로 아무도 다시 건네지 않았을 뿐이다.

정의

단위: 명단 한 벌이 원천 시스템에서 소비 시스템으로 건너가는 한 번의 전달이다.

범위: 전달을 누가 시작하는지, 언제 일어나는지, 무엇이 최신인지를 다룬다.

제외 대상: 명단에 무엇이 들어가는지, 사람을 무엇으로 가리키는지, 누가 명단을 고칠 수 있는지는 이 글의 범위가 아니다.

실패 조건: 두 시스템이 서로 다른 시점의 명단을 각자 최신이라고 부르는 상태다.

파일로 넘기는 방식

원천 시스템이 명단을 정해진 칸 이름의 표로 적어서 한 벌로 건넨다. 전달을 시작하는 쪽은 원천이다.

파일로 넘길 때

건넨 시점이 명확하다는 것이 이 방식의 성질이다. 3월 2일에 넘긴 파일은 3월 2일의 명단이고, 그다음 파일이 올 때까지 소비 시스템은 그 상태를 유지한다. 대신 그 사이에 생긴 전입은 아무도 모른다.

소비 시스템이 필요할 때 원천에 물어본다. 전달을 시작하는 쪽이 반대다.

API로 조회할 때

물어본 순간이 최신이라는 것이 이 방식의 성질이다. 대신 원천 시스템이 응답하지 못하면 소비 쪽에는 명단이 없다. 파일 방식이라면 오래된 명단이라도 남아 있었을 자리다.

네 줄 중에 마지막 줄이 운영에서 가장 크게 갈린다. 사본이 양쪽에 있으면 언젠가 두 사본이 어긋나고, 어느 쪽이 맞는지 판단할 기준을 따로 정해야 한다. 사본이 하나면 그 문제는 없지만, 원천의 응답 가능 여부가 곧 학습 화면의 가용성이 된다.

전체를 다시 건네는 부담을 줄이려고, 규약은 각 줄에 상태와 마지막 수정 시각을 두는 칸을 정해 놓았다. 이 칸을 쓰면 바뀐 줄만 골라 넘기거나 조회할 수 있다. 칸의 영어 이름은 아래 출처에 있다.

두 방식은 표준의 서로 다른 버전이 아니다. 같은 표준이 정한 두 가지 전달 방식이고, 한 기관이 둘을 같이 쓸 수도 있다. 학기 초에 전체를 파일로 한 번 맞추고, 그 뒤의 변경만 조회로 따라가는 조합이 그런 경우다.

두 방식은 우열의 문제도 아니다. 원천 시스템이 상시 응답할 수 있는지, 소비 시스템이 명단 없이 화면을 열어도 되는지에 따라 답이 달라진다. 이 조건을 적지 않고 “API가 낫다”고 쓰면 판단 근거가 남지 않는다.

전달 방식은 인증 방식과도 다르다. 파일을 어디에 두고 누가 가져갈지, 조회 요청에 어떤 자격을 요구할지는 별도의 층위다.

이 글의 범위는 전달 방식까지다. 아직 다루지 않은 내용은 아래와 같다.

이 사이트에서 이 선택을 제품 연동에 적용하는 자리는 STLink다. 아직 공개할 연동 건수가 없으므로 이 글에는 수치를 적지 않는다.