올바른 API란?

https://medium.com/@techworldwithmilan/rest-api-design-best-practices-2eb5e749d428

REST API Design Best Practices

커리어리 + Medium 글을 보고 정리해본 REST API

* API

• 라이브러리를 이용할 수 있도록 규칙 등을 정해 놓은 인터페이스
• 개발자 모두에게 중요한 요소.
• Application Programming Interface, 소프트웨어간의 커뮤니케이션 채널
• API 요청을 전송하는 클라이언트와 API 응답을 전송하는 서버 간 통신

" Application Programming Interface "(API)는 다양한 소프트웨어 서비스 간의 통신 채널입니다. 요청과 응답을 전송하는 애플리케이션을 각각 클라이언트와 서버라고 합니다. API 는 다른 프로그램에서 프로그램 기능을 사용할 수 있도록 하는 외부 소프트웨어 구성 요소입니다.

* API 프로토콜

• REST— API의 프런트엔드와 백엔드를 분리하고 개발 및 구현에 상당한 유연성을 제공하는 클라이언트/서버 접근 방식을 사용
• RPC — RPC( remote procedural call ) 프로토콜은 여러 매개변수를 보내고 결과를 받는 방식
• SOAP — HTTP, SMTP, TCP 등 인터넷에서 발견되는 광범위한 통신 프로토콜을 지원
• WebSocket — 지속적인 연결을 통해 브라우저와 서버 간에 데이터를 교환하는 방법을 제공

* API권장사항

• 시스템 간의 표준 통신 방법은 API를 통한 것이라 향후 문제를 방지하려면 REST API를 올바르게 구축하는 것이 중요하다.
• 잘 정의된 API는 작업하기 쉽고 간결하며 오용하기 어려워야 한다.

1. 동사대신 명사 사용
2. 복수형 자원명사를 사용
3. 일관성 유지하기 (리소스에 대해 동일한 사례, 모든 엔드포인트에 대해 동일한 인증 방법, 동일한 헤더, 동일한 상태 코드 사용)
4. 사용자의 적절한 상태코드 (API 전체에서 동일한 결과에 대해 동일한 상태코드 사용하기)
5. 일반 텍스트를 반환하지 말기
6. 적절한 오류 처리를 수행하기 (오류를 처리하고 무슨 일이 일어났는지 응답코드(400 ~ 5xx)를 반환)
7. 보안 관행을 갖추기(예외없이 항상 SSL/TLS사용, 만료날짜가 있는 사용자 정의 HTTP헤더 사용)
8. 페이지 매김 사용
9. 버전관리
10. API문서화하기