REST API 설계

API (Application Programming Interface)란?

• 컴퓨터나 컴퓨터 프로그램 사이의 연결
• 일종의 소프트웨어 인터페이스이며 다른 종류의 소프트웨어에 서비스 제공

목적 : 시스템이 동작하는 방식에 관한 내부의 세세한 부분을 숨긴다.

✅ 일정하게 관리할 수 있는 부분만 노출

✅ 내부의 세세한 부분이 나중에 변경되더라도 프로그래머가 유용하게 사용 가능

 

 

REST API 란?

REST 아키텍처 스타일을 따르는 API

REST(Representational State Transfer)

API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처

 

REST 아키텍처 원칙

균일한 인터페이스

서버가 표준 형식으로 정보 전송

ex) 균일한 리소스 식별자 사용, 서버는 리소스를 자세히 설명하는 메타데이터 전송 등등

 

무상태(Stateless)

독립적인 쌍의 요청과 응답으로 구성

 

계층화 시스템

클라이언트에 보이지 않는 상태로 다중 계층의 REST 서버로 구성 가능

API 서버 + 사용자 인증, 암호화, 로드밸런싱 계층 추가 

 

캐시 가능성

서버 응답시간을 개선하기위해 일부 응답을 저장하는 프로세스인 캐싱 지원

 

온디맨드 코드

서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송 가능

   ➡️ 클라이언트 기능을 일시적으로 확장하거나 사용자 지정할 수 있다.

👾 client에 실행 가능한 프로그래밍 코드를 전송하여 client에서 실행

 

ex) 클라이언트가 잘못된 전화번호 입력시 즉시 실수 표시

 

REST API 구성

🔵 자원 - URI

🔵 행위 - HTTP Method

🔵 표현

 

API 설계

3가지 질문에 대한 답을 제시할 수 있어야한다.

1. API를 구현하고자 하는 이유 (목적)은 무엇인가?

• API로 인한 효과의 가치를 생각하기
  • 기업의 핵심 비지니스, 전달하는 가치를 제공하는 채널 생성
  • 사용자에게 API가 제공하는 가치는 API 호출에 따른 결과이다.

2. API를 통해 실현하고자 하는 구체적인 성과는 무엇인가?

= API가 실제로 어떤 역할을 하고 비지니스 큰 그림에서 어떤 영향을 주는가?

• 제공하는 서비스와 리소스의 가치가 높고 고유할수록 API에 적합하다.
• 고유한 데이터를 보유할 경우 리소스를 활용할 수 있다.

3. 원하는 성과를 실현하기 위해 어떤 방법으로 API 프로그램을 설계할 것인가?

• API 구축 기술
• API 설계 및 관리 방법
• API 외부 공개 및 기업 내부 사용 방법

 

REST API 설계 디자인

1. URI는 정보의 자원을 포함해야한다.

리소스 명은 동사보다는 명사를, 대문자보다는 소문자를 사용한다.

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

URI에 HTTP Method나 동사 표현이 들어가면 안된다.

:id와 같이 변하는 값은 하나의 특정 리소스를 나타내는 고유값이어야한다.

 

예시

❌ GET /products/delete/:id

⭕️ DELETE /products/:id

 

URI 설계 주의사항

1. 슬래시 구분자(/)는 계층관계를 표현한다.

/ 뒤 pk 위치: /users/1

     select * from user where id = 1;

pk가 아닌 것들은 쿼리로 처리 ex) /users?loc=서울

     select * from user where loc = '서울' (X)

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

3. 하이픈(-)은 사용가능하지만, 밑줄(_)은 사용하지 않는다.

✅ 하이픈(-)은 가독성을 높이는데 사용한다.

✅ 밑줄 대신 하이픈을 사용하자.

 

4. URI 경로에 대문자 사용을 피하고, 소문자를 사용하자.

❕ 대소문자에 따라 다른 리소스로 인식된다.

 

5. 파일 확장자는 URI에 포함시키지 않는다.

✅ Accept header를 사용한다.

 

❌ http://restfulservice.com/products/pencil.jpg

⭕️ GET / products/pencil HTTP/1.1

     Host: restfulservice.com

     Accept: image/jpg

 

 

REST API 설계 예시

• 사용자 조회
  • GET :  /users
• 특정 사용자 조회
  • GET : /users/{id}
• 새로운 사용자 생성
  • POST : /users
• 특정 사용자 수정
  • PUT : /users/{id}
• 특정 사용자 삭제
  • DELETE : /users/{id}

 

REST API에 강제성은 없다.

좋은 주소를 설계하여 협업할때 모호하지 않게 해주는 규칙이지, 강제 규약은 아니다.

만약 Restful하지 않은 주소라도, 이미 작업하는 동료들끼리 정한 규칙이라면 따르는 것이 일반적이다.

 

 

참고 링크

https://ko.wikipedia.org/wiki/API

API - 위키백과, 우리 모두의 백과사전

https://aws.amazon.com/ko/what-is/restful-api/

RESTful API란 무엇인가요? - RESTful API 설명 - AWS

 

https://www.redhat.com/ko/topics/api/what-is-api-design

API 설계란?

https://meetup.nhncloud.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup