티스토리 뷰
Overview
REST API에 대해서 알아보고, 조금더 탄탄한 설계를 해봅시다
REST API 란?
REST(REpresentational State Transfer)란,
웹에 존재하는 모든 자원(이미지, 동영상, DB 자원)에 고유한 URI를 부여해 활용하는 것으로,
자원을 정의하고 자원에 대한 주소를 지정하는 방법론을 의미한다고 한다.
따라서 RESTful API는 REST 특징을 지키면서 API를 제공하는 것을 의미한다.HTTP 프로토콜에서 HTTP METHOD 와 URI를 통해 리소스를 주고받는 것
Restful 하게 하는 6가지 조건
- Uniform Interface
HTTP 표준만 따르면, 특정언어나 플랫폼에 종속받지 않고 사용 가능함(파이썬, Java, Javascript,웹, iOS, iOS, 안드로이드 어떤 언어와 플랫폼이든 상관없음)
- Client-Server
모든 통신은 클라이언트-서버 간의 일대일로 연결
- Stateless
클라이언트의 Context가 서버에 저장되지 않는다. 상태정보를 저장하지않고, 들어온 요청만 처리함 Stateless 시스템에서 서버는 클라이언트의 요청을 처리했던 이력을 저장하지 않는다. 그렇기 때문에 각각의 요청에 해당 정보가 포함되어야 한다.
- Cacheable
Rest API URI에 요청에 대한 리소스가 들어있기 때문에, 각 리소스에 대해 캐싱이 가능함
- Layered System
서버는 클라이언트가 모르게 API 서버에 여러 계층을 추가하여 유연한 구조로 개발될 수 있다.
- Code on Demand(optional)
클라이언트는 리소스에 대한 표현을 응답으로 받고 처리해야 하는데, 어떻게 처리해야 하는지에 대한 Code를 서버가 제공하는 것을 의미한다.
Http Method
| METHOD | 설명 |
| POST | 해당 URI를 요청하면 리소스를 생성 |
| GET | 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져옴 |
| HEAD | GET과 동일하지만, 응답에 BODY가 없고 응답코드와 HEAD로만 응답 |
| PUT | 리소스를 수정 |
| PATCH | PUT과 같이 리소스를 업데이트함. PUT의 경우 자원 전체를 갱신하는 의미지만, PATCH는 해당자원의 일부를 교체하는 의미로 사용 |
| DELETE | 리소스를 삭제 |
| CONNECT | 동적으로 터널 모드를 교환, 프락시 기능을 요청시 사용 |
| TRACE | 원격지 서버에 루프백 메시지 호출하기 위해 테스트용으로 사용 |
| OPTION | 웹서버에서 지원되는 메소드의 종류를 확인할 경우 사용 |
Rest API 설계해보기
- Depth는 최소한으로
`Bad`
GET /employees/privacy/salary/memo
`Good`
GET /employees/records- 행위를 URL에 포함하지 않는다
`Bad`
GET /employees/find-all
GET /employees/find/{id}
POST /employees/create
PUT /employees/update/{id}
DELETE /employees/remove/{id}
`Good`
GET /employees
GET /employees/{id}
POST /employees
PUT /employees/{id}
DELETE /employees/{id}- case 통일
- kebab case를 많이 사용(가독성)
GET /employees/post-comments
- 대문자보다는 소문자로 표현하기
`Bad`
GET /employees/{id}/deviceCount
`Good`
GET /employees/{id}/devices- 동사보다는 명사로 표현하기
- HTTP Method에 의해 CRUD (생성,읽기,수정,삭제)의 대상이 되는 개체를 명사로 표현
POST /employees/salary- 복수형으로 통일하기
`Bad`
POST /user
POST /corp
POST /employee
`Good`
POST /employees- 리소스 간 관계를 나타내기
/{리소스명}/{리소스 id}/{관계가 있는 다른 리소스명}
GET /employees/{id}/devices- 에러 처리
- HTTP STATUS CODE 활용
`Bad`
Http Status Code : 200 OK
{
"code" : 400,
"msg" : "Bad Request"
}
`Good`
Http Status Code : 400 Bad Request
{
"code" : "INVALID_PARAMETER",
"errors" : [
{ "userMessage": "Please enter a valid name",
"internalMessage": "Not allowed English name in KOR field.",
"more info": "http://gowid.com/api/v2/errors/12345"
}
]
}
- 상황에 맞는 HTTP STATUS CODE
POST /employees
-d '{
"name" : "leo",
"role" : "manager"
}'
`Not Bad`
Http Status Code
200 OK
`Good`
Http Status Code
201 Created조금 더 Restful 하게.. Hateoas
HATEOAS 사용 해보기
HATEOAS란?
RESTful API를 사용하는 클라이언트가 전적으로 서버와 동적인 상호작용이 가능하도록 하는 것을 HATEOAS라 합니다.
서버/클라이언트에서의 관점
- Server-side : 해당 리소스와 관련 된 동적인 링크를 같이 응답한다.
- Client-side : 응답받은 링크를 통해 연관된 리소스를 찾는다.
모든 동작을 URI를 이용하여 동적으로 알려준다.
HATEOAS 예시
None-Hateoas
- Handler
@GetMapping("/employees/{id}")
Employee one(@PathVariable Long id) {
return repository.findById(id)
.orElseThrow(() -> new EmployeeNotFoundException(id));
}- Response
{
"id": 2,
"name": "Frodo Baggins",
"role": "thief"
}Hateoas
- Handler
@GetMapping("/employees/{id}")
EntityModel<Employee> one(@PathVariable Long id) {
Employee employee = repository.findById(id)
.orElseThrow(() -> new EmployeeNotFoundException(id));
return EntityModel.of(employee,
linkTo(methodOn(EmployeeController.class).one(id)).withSelfRel(),
linkTo(methodOn(EmployeeController.class).all()).withRel("employees"));
}- Response
{
"id": 2,
"firstName": "Frodo",
"lastName": "Baggins",
"role": "thief",
"name": "Frodo Baggins",
"_links": {
"self": {
"href": "http://localhost:8080/employees/2"
},
"employees": {
"href": "http://localhost:8080/employees"
}
}
}참고
댓글