오픈 API 문서를 읽을 때 주의할 점

 

 저는 지금까지 API를 연결할 때 swagger문서만을 활용했었습니다. 이번 사이드 프로젝트를 통해 처음으로 오픈 API 문서를 활용해 작업을 하게 되었습니다. 이에 구글링과 GPT 및 제미나이를 활용하여 오픈 API 문서를 활용할 시 주의할 점을 알아보고 이를 참고해 작업에 참고해보고자 합니다.

 

1. 구현하고자 하는 기능과 API가 정말 일치하는가 확인

사실프로젝트 시작전부터 확인해야 하는 사항으로 해당 API가 만들고자 하는 기능과 일치하는 지를 확인해야 합니다.

 

2. 어떤 필드만 가져올지 계획

API의 응답 형식을 바로 UI에 쓰는 것은 지양해야 합니다. 필드명을 바로 쓰지 말고 내부 타입으로 정규화 하거나 매핑해야 합니다.

 

3. 샘플 데이터 품질 확인

샘플 데이터 몇 개를 확인하여 값이 비어있으면 어떻게 처리할 지, 문자열을 배열로 쪼갤지 등을 생각해보고 null/빈 문자열, 형식 차이를 체크합니다.

 

4. 공식문서의 설명보다 샘플 구조가 더 정확할 수 있음을 인지

공식 문서에 오류가 있거나 예전 설명이 남아 있을 수도 있습니다. 필드 목록, 샘플 데이터, 실제 호출 결과 확인을 꼭 해봐야 합니다.

 

5. 호출 제한 확인

해당 데이터 활용 서비스 페이지를 통해 어떤 호출 제약이 있는지 확인해야 합니다. 만약 호출 제한을 확인하지 않고 제한 이상으로 과하게 호출하는 구조로 개발했다면 나중에 번거롭게 수정을 해야 합니다.

 

6. 이용허락범위와 출처표시 조건 확인

항상 허락범위내에서만 API를 활용해야 하며 README나 서비스 하단에 출처 표기를 넣는 방식으로 출처를 표시해야 합니다.

 

7. 키 관리와 호출 위치를 사전에 고려

실제 API를 연결할 때는 브라우저에 직접 하기 보다는 Next.js Route Handler를 통해 서버 쪽에서 호출하는 방향이 안전합니다.

 

8. 이미지 URL은 반드시 실제 접근 가능 여부를 확인

원격 이미지 도메인 설정 문제가 생길 수도 있으니 테스트 단계에서 반드시 브라우저에 실제 이미지가 잘 뜨는지까지 확인해야 합니다.