Basic
1
2
3
4
5
6
POST /users HTTP/1.1
{
“users”:{
“name”:”Joo”
}
}
/users라는 Resource에 Request body에 맞게 새로운 리소스를 생성POST해라
HTTP method란?
- POST, GET, DELETE, PUT, PATCH, HEAD, OPTIONS 등
- 멱등성 (Idempotent) :
POST는 멱등하지 않아서 일반적으로 계속 요청하면 계속 side effect가 있을 것이라고 기대하고 나머진 멱등하게 구성한다. - safe method:
GET,HEAD는 resource에 side effect를 주지 않는다. CORS 정책의 simple request는 해당 메소드들이 가능하다. 덧붙이면 POST도 기존의 resource를 변경하지 않기 때문에 safe하다고 판단한다. - 형태:
Method /resource/{resourceId}
좋은 API 디자인
- 각각의 http method 성격을 위반하지 않아야 한다.
- e.g)
GET메서드는 어떠한 상태를 변경하지 않고,POST는 리소스를 생성한다.get메서드가 uri에 리소스를 노출한다고해서 조회 API에 post를 사용하면 혼동이 올 수 있다.
- e.g)
- URI만 보고도 무슨 API인지 알도록 직관적으로 작성해야한다. Resource간의 관계를 표현한다고 생각하면 편하다.
/rooms/{roomId}/participants/{participantId}
- Resource는 대상은 명사, 복수형을 사용한다. 의미상 이게 명확하다.
/rooms/{roomId}: 모든rooms중roomId에 해당하는 room/rooms/: 모든 rooms
1
2
3
나쁜 예)
POST /getDogs
POST /setDogOwner
1
2
3
좋은 예)
GET /dogs
POST /dogs/{dogID}/owner
- http status code를 의미에 맞게 적절히 사용해야 명확하다. 예를 들어, 클라이언트 에러인데 500번대 status를 전달하면 올바르지 않은 설계이다.
- 보안을 위해 Error stack은 response 메시지에 포함 시키지 않는다. 적절한 비즈니스 에러를 던지는 편이 좋아보인다.
- 페이징: 많은 도큐먼트 리턴시 잘라서 리턴하는 페이징 처리 필요
/records?offset=100&limit=25 (100번째 record부터 25개 출력)- ``/records?page=5&rpp=25`
/records?start=50&count=25
부하를 낮추기 위한 부분 응답 방식. 패킷 사이즈를 줄일 수 있다. 이러한 비즈니스적인 처리가 좋은 설계를 만들 것 같다.
/people:(id,first-name,last-name,industry)- 파싱에 어려움/terry/friends?fields=id,name- 직관적?fields=title,media.address.city
- API version을 갖게 하는 것도 관리 측면에서 좋다. URI에
/v1/rooms와 같이 버전을 명시해, 각각의 버전으로 맵핑될 수 있도록한다. 버전 설계에는 항상 하위호환을 고려해야한다. - camel case보다는 dash나 snake case가 좋아보인다. 팀원과의 상의 필요하고 컨벤션을 정해놓는게 나중에 관리가 편하다.
- 개발자 뿐 아니라 일반 사용자들도 브라우저에서 접근 할수 있음을 염두한다.
- HATEOAS - restful하게 만드는 대표적인 특징 중 하나이다. client는 link를 통해서 api에 접근 가능하게 되고, client와 server가 독립적으로 분리 가능해진다. 그런데, 일반적으로 api 서버가 커질 수록 관리 포인트가 많아지고 hateoas가 지켜지기 어렵다.
- Stateless를 유지해야한다. -> 토큰, 쿠키 활용 혹은 세션 서버(redis 등)
- 문서화: Swagger UI는 뚱컨이 될 우려가 있고, Restdocs는 동시에 테스트 코드 작성이 가능하다.
Reference)
https://www.slideshare.net/Byungwook/rest-api-60505484
https://developer.mozilla.org/ko/docs/Web/HTTP/Methods
https://www.slideshare.net/brotherjinho/restful-api-64494716