기술 문서 : https://medium.com/@techworldwithmilan/rest-api-design-best-practices-2eb5e749d428
API는 다양한 소프트웨어 서비스 간의 통신 채널을 의미합니다.
API 프로토콜들은 다음과 같이 다양한 유형이 존재합니다.
- REST - API의 프론트엔드와 백엔드를 분리하고 개발 및 구현에 상당한 유연성은 제공하는 클라이언트 / 서버 접근 방식을 사용합니다.
- RPC - 여러 매개변수를 보내고 결과를 받습니다.
- SOAP - HTTP, SMTP, TCP 등 인터넷에서 발견되는 광범위한 통신 프로토콜을 지원합니다.
- WebSocket - 지속적인 연결을 통해 브라우저와 서버 간에 데이터를 교한하는 방법을 제공합니다.
시스템 간의 표준 통신 방법은 API를 통하고 있고 소프트웨어 엔지니어로서 업무의 대부분은 REST API를 활용하거나 생성하는 일을 수행합니다.
따라서 향후 문제를 방지하려면 REST API를 올바르게 구축하는 것이 중요합니다.
잘 정의된 API는 작업하기 쉽고, 간결하며, 오용되기 어려워야 합니다.
다음은 몇 가지 일반적인 권장 사항을 소개합니다.
1. 동사 대신 명사 사용하기
엔드포인트 경로에는 동사를 사용하면 안됩니다.
대신, 경로 이름에는 우리가 엑세스하거나 변경하는 엔드포인트가 속한 개체를 식별하는 명사가 포함되어야 합니다.
예를 들어, 모든 클라이언트를 가져오는 API의 엔드포인트를 /getAllClients 대신 /clients를 사용해야 합니다.
이는 엔드포인트를 최대한 간결하게 유지하기 위함으로
가져오는지, 수정하는지에 대한 정보는 GET, POST와 같은 method로 표현해야 합니다.
2. 복수 리소스 명사 사용하기
모든 유형의 엔드포인트에 적합하므로 리소스 명사에는 복수형을 사용합니다.
예를 들어, /employee/:id/를 사용하는 대신 /employees/:id를 사용합니다.
3. 일관성을 유지하기
일관성이 있다는 것은 예측 가능하다는 것을 의미합니다.
하나의 엔드포인트를 정의하면 다른 엔드포인트도 비슷하게 동작해야 합니다.
따라서 리소스에 대해 동일한 사례, 모든 엔드포인트에 대해 동일한 인증 방법, 동일한 헤더, 동일한 상태 코드 등을 사용해야 합니다.
4. 간결성을 유지하기
우리는 모든 엔드포인트의 이름을 그대로 리소스 지향적으로 지정해야 합니다.
사용자를 위한 API를 정의하려면 다음과 같이 설명해야 합니다.
/users
/users/124
첫번째 API는 모든 유저에 대한 정보를 가져오는 API이고 두번째 API는 유저의 세부 정보를 가져오는 API입니다.
5. 적절한 상태 코드 사용하기
이것은 매우 중요한 사항입니다.
HTTP 상태 코드는 많지만 일반적으로 일부만 사용합니다.
너무 많이 사용하지 말고 API 전체에서 동일한 결과에 대해 동일한 상태 코드를 사용하는 것이 좋습니다.
200은 일반적인 성공인 경우 사용합니다.
201은 성공적으로 생성되었을 때 사용합니다.
202는 성공적인 요청을 받았을 때 사용합니다.
204는 컨텐츠가 없지만 에러는 아닌 경우에 사용합니다.
307은 리다이렉션 컨텐츠에 경우 사용합니다.
400은 잘못된 요청인 경우에 사용합니다.
401은 인증되지 않은 요청일 때 사용합니다.
403은 권한이 없는 경우에 사용합니다.
404는 리소스 부족인 경우 사용합니다.
500은 내부 서버 오류의 경우 사용합니다.
6. 일반 텍스트 반환하지 않기
REST API는 데이터 전송을 위한 표준이기 떄문에 JSON을 요청 페이로드로 수락하고 JSON으로 응답해야 합니다.
그러나 JSON 형식의 문자열로 본문을 반환하는 것만으로 충분하지 않습니다.
Content-Type 헤더를 application/JSON으로 지정해야 합니다.
유일한 예외는 클라이언트와 서버 간에 파일을 보내고 받으려는 경우 뿐입니다.
7. 적절한 에러 처리하기
오류가 발생했을 때 혼란을 없애기 위해 우리는 오류를 적절하게 처리하고 무슨 일이 일어났는지 나타내는 응답 코드를 반환해야 합니다.
상태 코드와 함께 응답 본문에 일부 세부 정보를 반환해야 합니다.
8. 좋은 보안 관행 찾기
우리는 클라이언트와 서버 간의 모든 통신이 보호되기를 원합니다.
즉, 예외 없이 항상 SSL/TLS를 사용해야 함을 의미합니다.
또한 만료 날짜가 있는 사용자 정의 HTTP 헤더를 사용하여 전달되어야 하는 API 키를 통한 인증을 허용합니다.
9. 페이지네이션 사용하기
API가 많은 데이터를 반환해야 하는 경우 페이지네이션을 사용하면 데이터가 많이 쌓인 미래를 대비할 수 있습니다.
page와 page_size를 파라미터로 받아 처리할 수 있습니다.
예를 들어, /products?page=10&page_size=20과 같이 사용할 수 있습니다.
10. 버전관리
API의 사용자가 다를 수 있으므로 첫 번째 버전부터 API 버전을 지정하는 것이 중요합니다.
이를 통해 사용자는 향후 발생할 수 있는 변경 사항으로 인해 영향을 받지 않도록 할 수 있습니다.
API 버전은 HTTP 헤더 또는 쿼리/경로 매개변수를 통해 전달될 수 있습니다.
예를 들어 /products/v1/4와 같이 사용할 수 있습니다.
또한, API는 문서화되어 있는 만큼만 유용하므로 API를 문서화하는 것을 잊으면 안됩니다.
문서에는 전체 요청/응답 주기의 예시가 포함되어야 합니다.
여기서는 OpenAPI 정의를 신뢰할 수 있는 출처로 사용할 수 있습니다.
API를 개발하려면 Swagger 및 OpenAPI 사양, Postman 또는 Stoplight를 확인하세요.
'기술문서 읽기' 카테고리의 다른 글
| React Native Navigation 기초 이해하기 (0) | 2024.02.24 |
|---|---|
| ASGI에 대해서 (1) | 2024.02.08 |
| 데이터베이스 최적화하는 방법 11가지 (0) | 2024.01.14 |
| Netflix에서 API를 탄력적으로 만드는 방법 (2) | 2023.12.31 |
| 대용량 데이터베이스에서 데이터를 효율적으로 Fetch 하는 방법 ( feat. Python Generator ) (0) | 2023.12.23 |
