- API?
Application Programming Interface 의 약자로 프로그램을 실행하는 인터페이스.
API를 통해 프로그램 요청을 전달하기 위한 통로 혹은 방법.
- RESTful API ?
REST는 Representational State Transfrer라는 용어로 2000년도 당시 HTTP 설계의 우수성에 비해 제대로 사용되지 못하는 모습에 로이필딩이 발표한 웹의 장점을 최대한 활용할 수 있는 아키텍쳐.
- RESTful API 에서 HTTP Method
1) GET : 조회
2) POST : 리소스 생성
3) PUT : 리소스 갱신
4) DELETE : 리소스 삭제
| Resource | GET(read) | POST(create) | PUT(update) | DELETE(delete) |
| /items | 상품 목록 보기 | 상품 추가 | ||
| /items/{id} | ID값 상품 보기 | ID값 상품 수정 | ID값 상품 삭제 |
- 설계 예시
| CRUD | HTTP | URI |
| 전체 리소스 조회 | GET | /resources |
| 특정 리소스 조회 | GET | /resources/:id |
| 리소스 생성 | POST | /resources |
| 리소스 전체 수정 | PUT | /resources/:id |
| 특정 리소스 삭제 | DELETE | /resources/:id |
* :id 와 같이 변하는 값은 특정 리소스를 나타내는 고유값이어야 한다.
- REST API 디자인 가이드
: URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP METHOD를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.
1) URI는 정보의 자원을 표현해야 한다. (리소스명은 명사를 사용)
- GET /members/delete/1 (x)
delete와 같은 행위에 대한 표현이 들어가면 안된다.
2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE) 로 표현한다.
- GET /members/delete/1 (x)
- DELETE /members/1 (o)
ex) 회원 정보를 가져오는 URI
GET /members/show/1 (x)
GET /members/1 (o)
회원 추가
GET /members/insert (x)
POST /members (o)
3) HTTP 응답 상태 코드
잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다.
- URI 설계 시 주의점
1) 슬래시 구분자(/)는 계층관계를 나타내는 데 사용한다.
http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales
2) URI 마지막 문자로 슬래시를 포함하지 않는다.
http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments (0)
3) 하이픈(-)은 URI 가독성을 높이는데 사용
불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있다.
4) 밑줄은(_) URI에 사용하지 않는다
5) URI 경로에는 소문자가 적합
대소문자에 따라 다른 리소스로 인식
6) 파일 확장자는 URI에 포함시키지 않는다
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않습니다. Accept header를 사용하도록 한다.
GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg
- 리소스 간의 관계를 표현하는 방법
REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용.
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현할 수 있다.
예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)