Chapter5 : API
📌목차
5-1) API의 개요
5-2) API의 유형
5-3) API 명세서
✅ 내용정리
API란 무엇인가?
API란 Application Programming Interface의 약자로 응용 프로그램에서 사용할 수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어하기 위한인터페이스이다.
인터페이스란 말 그대로 어떤 기계간의 장치끼리 정보를 교환하기 위한 수단이나, 방법을 의미한다.따라서, API는 어떤 특정 사이트에서 특정 데이터를 공유할 경우 어떠한 방식으로 정보를 요청해야 하는지, 그리고 어떠한 데이터를 제공 받을 수 있을지에 대한 규격들을 API 라고 볼 수 있다.
클라이언트 - 서버 간 API 개발 순서
클라이언트 - 서버 간에 API 개발 순서는 다음과 같다.
1) 엔드포인트 설계 : ~~/search , ~~user 와 같은 최종 경로
2) HTTP 메서드 지정 : GET / POST / PUT,PATCH / DELETE 등
3) 데이터 포맷 및 프로토콜 선택 : JSON / XML 등
4) 엔드포인트 구현
5) 인증 및 보안
6) 오류 및 예외 처리
7) 테스트와 디버깅
8) API 문서화 : 엔드포인트 / 매개변수 / 응답 형식 / 오류 코드 등
REST API란 무엇인가?
REST API란, API에서 더 나아가서 개발자마다 너무 서로 다른 형식의 API 생성을 방지하고자
REST라는 형식과 규약을 넣어서 만든 API라고 볼 수 있다.
REST API를 제대로 쓰기 위해, 여러 REST의 원칙과 제약을 준수하여 설계한 API를RESTful API라고 칭한다.
REST API의 구성요소
크게 자원 / 행위 / 표현으로 구성되어 있다.
1) 자원 : 클라이언트와 서버 간에 주고받는 자원을URI로 명시한다.
2) 행위 : HTTP 메서드를 통해 해당 자원에 대한 CRUD 연산을 수행한다.
3) 표현 : 주고받는 자원의 데이터 표현 방법을 명시한다. ( JSON / XML )
REST API 의 장점
REST API 방법을 사용하면 주소와 메서드만 보고 요청의 내용을 알아볼 수 있다는 장점이 있다.
따라서 개발자간의 소통이 좀 더 원활하다.
REST의 특징
1) Client-server architecture : 클라이언트와 서버를 명확하게 분리한다.
2) Stateless : 서버는 클라이언트에 대한 사전 정보나 클라이언트의 상태를 저장하지 않는다.
3) 캐시 처리 기능
4) 계층 구조
5) 인터페이스 일관성
6) 자체 표현 등
REST API 설계규칙
1) URI에 명사만을 사용한다,
2) 두 명사가 붙을 경우엔 하이픈을 사용한다,
3) 오직 소문자를 사용한다,
4) 행위에 대한건 HTTP Method에게 맡긴다.
5) 자원의 계층관계를 / 로 나타낸다.
6) 마지막에 / 를 넣지 않는다.
7) 적절한 HTTP 상태 코드를 응답한다. 등
API 문서화 도구 : (Swagger VS Spring REST docs)
자주 사용하는 2가지 도구로는 Swagger 와 Spring REST docs가 있다.
팀 스타일과 환경에 따라서 골라서 선택하면 된다.
Swagger장점
- Spring REST docs에 비해 쉽게 API 문서를 생성할 수 있다.
- UI와 편의성 깔끔하다.
단점
- 스웨거(swagger)는 운영코드에 침투적이다 -> 어노테이션을 활용 해야 하므로 코드가 지저분해진다.
- "Springdoc"가 제공하는 기본 기능만 활용한다면 "Springfox"에 비해서 운영코드에 침투력이 줄어든다. (그래도 침투적이다.)
Spring REST docs장점
- Spring REST Docs 는 테스트를 반드시 작성해야 한다. -> 신뢰도 증가
- 이유 : API 문서에 포함(include)되는 "스니펫(snippets)"을 생성하기 위해 테스트 코드를 작성해야 한다.
- 운영코드에 침투하지 않는다.
단점
- 정적인 HTML 문서기 때문에 "Spring REST Docs" API 문서는 뭔가 심심하다. 개발자 외에 기획자가 테스트하려고 하면 뭔가 불편하다.
- 밋밋한게 아쉽다면, Spring REST Docs 에 Swagger 를 넣을 수 있다. (보통 이렇게 많이 사용함)
- 준비 사항과 진입 장벽이 매우 높다.
[참고] https://helloworld.kurly.com/blog/spring-rest-docs-guide
