pdf 변환의 진행 상황 표시 피드백 반영을 위한 API 수정 제안

[gitchannn]

지난 유저 테스트 때 받았던 진행 상황이 얼마나 되고 있는지 모르겠어서 답답하다는 피드백을 반영하기 위해서 현재 클라이언트와 서버 사이에 이루어지고 있는 API를 크게 수정하는 것을 건의하려고 합니다.
현재까지의 진행 방식을 위에서 간략히(?) 설명하고, 변경하고 싶은 방식을 아래에 설명하겠습니다.

현재 진행 방식

해바라기 팀 내 API는 2가지입니다.

1. PDF 요청 API #8

사용자로부터 업로드받은 pdf를 클라이언트가 서버로 보내고, 201 CREATED와 함께 서버 내 저장된 translations의 식별자를 받습니다.
현재 구현으로 이때 서버는 실제로 Mathpix API를 호출하고, 응답으로 pdf_id를 받습니다. 이 아이디는 Mathpix에서 자체적으로 생성한 것으로, 해당 요청은 비동기적으로 진행되어 id를 받는 시점에도 Mathpix API는 OCR 작업 중에 있습니다.

PDF ID: 2024_02_18_7698218eb2adeae7xxxxxxx

서버에서 이후 요청부터는 이 아이디를 포함해 실제 OCR 결과 반환을 위해 요청을 보냅니다.
하지만, Mathpix 서버에서 OCR 처리가 완료되기 전까지는 실제 결과 대신에 진행 상황을 퍼센트로만 알 수 있습니다.

{"status":"split","version":"RSK-P111p2","input_file":"28번.pdf","num_pages":1,"num_pages_pdf":1,"percent_done":0}

실제로 완료과 되면 아래와 같은 형태의 응답을 받을 수 있습니다.

{"status":"completed","version":"RSK-P111p2","input_file":"28번.pdf","num_pages":1,"num_pages_pdf":1,"num_pages_completed":1,"percent_done":100}

서버는 completed를 확인한 후에 받은 파일을 (여기부터는 예정) 데이터베이스에 저장해 두고, 해당 식별자를 클라이언트에 반환합니다.

2. PDF 반환 API #9

앞선 1번 API를 호출한 뒤 반환받은 translations의 식별자를 포함해 서버에 요청을 보내고,
서버는 데이터베이스로부터 해당 식별자의 파일을 응답합니다.

여기까지가 현재 상황이고, 저는 이 프로세스를 좀 변경해서 아래와 같이 하고 싶습니다.

---

변경 제안

1. PDF 요청 API

비동기적으로 처리해서, pdf 업로드 요청을 받으면 곧바로 식별자는 반환하되 응답 이후에 OCR 변환 작업이 진행되도록 변경하고 싶습니다.
그러니깐, 이제 위에서 설명한 1번 API를 통해 전달받은 식별자로 2번 API를 호출하더라도 곧바로 파일을 응답할 수 없는 상태가 되는 것이죠.
Mathpix API에서 받은 pdf_id로 곧바로 OCR 완료된 파일을 받을 수 없던 것과 비슷합니다.

기존 방식과 API 스펙은 동일합니다.

Request

Header

POST /translate-pdf

Content-Type: multipart/form-data

Body

• file: Multipart 폼 데이터로 수학 문제를 촬영한 pdf 전달

Response

Header

HTTP/1.1 201 CREATED

Location: translations/{id}

• 이때 서버는 원본 pdf를 데이터베이스에 저장하고 받은 id를 반환할 뿐, 아직 OCR은 진행되지 않습니다.
• pdf를 계속 가지고 있어도 되는지 여부는 법적 검토를 받아야겠지만, 일단 잠시 저장하고 변환 후 hard delete하는 것으로 구현하겠습니다.

Body

None

2. translations 진행 상황 확인 API

이 API를 지난 유저 테스트 때 받았던 진행 상황 표시에 대한 내용으로 사용하려고 합니다.
클라이언트는 status를 확인해 completed가 아니면 계속해서 polling 방식으로 1초(혹은 어느 정도의 시간 텀)마다 진행 상황을 업데이트하면 좋을 것 같습니다.
이 API는 response body에서 status=completed를 받을 때까지 계속 호출해 주세요.
화면에는 OCR 변환중... 33% 이런 식으로 띄워 주시면 유저의 답답함을 어느정도 해소할 수 있을 것 같아요.

Request

Header

GET /translations/{id}/status

Body

None

Response

Header

HTTP/1.1 200 OK

Body

{
  "id":  {id}, 
  "status": "split",
  "file_name": "28번.pdf",
  "percent_done": 33
}

• id, file_name은 Over fetching일 수 있지만, id는 좀 더 restful하게 사용하기 위해, 그리고 file_name은 헷갈리는 경우에 실수를 방지하기 위해 포함했습니다.

3. 점자 번역 결과 반환 API

위의 2번 API에서 response body로 completed를 받으면 이 API를 호출해 주세요.

Request

Header

GET /translations/{id}

Body

None

Response

Header

HTTP/1.1 200 OK

Body

• translations: 점역 완료된 brf 파일