카드(할 일), 아이템, 히스토리를 다루는 API의 문서를 작성하면서 정리한 내용이다.
정수 나눗셈의 결과
(2+3)/2 => 2??!?
Java에서 int끼리의 나눗셈은 정수 나눗셈이라 소수부를 버린다. Java 언어 명세에 따르면 정수 나눗셈은 0 방향으로 반올림(truncation)하므로 (2 + 3) / 2는 2.5가 아니라 2다. 음수에서도 -5 / 2는 -3이 아니라 -2가 된다. 소수 결과가 필요하면 피연산자 하나를 double로 바꿔 (2 + 3) / 2.0처럼 쓴다. 이진 탐색에서 중간값을 (low + high) / 2로 구할 때 이 성질을 그대로 쓰며, 두 값이 크면 덧셈이 int 범위를 넘을 수 있어 low + (high - low) / 2로 쓰는 편이 안전하다.
2 + 4, 3 + 4, 4 + 4, 5 + 4, …
1
| [GET] {server address}/cards
|
API Document
리소스는 카드(cards), 아이템(items), 히스토리(histories) 세 가지다. 각 리소스의 생성, 조회, 수정, 삭제를 HTTP 메서드로 구분하고, 개별 리소스는 /{id} 경로 변수로 지정한다. 아래는 초안이라 응답 본문은 생성되거나 영향을 받은 리소스의 ID만 적어 두었다.
Card API
Card Create
1
2
3
| {
"cardId" : "{cardId}"
}
|
Card Read
1
2
3
| {
"cardId" : "{cardId}"
}
|
Card Update
1
| [PUT] /api/cards/{cardId}
|
1
2
3
| {
"cardId" : "{cardId}"
}
|
Card Delete
1
| [DELETE] /api/cards/{cardId}
|
1
2
3
| {
"cardId" : "{cardId}"
}
|
Item API
Item Create
1
2
3
| {
"cardId" : "{cardId}"
}
|
Item Read
1
2
3
| {
"cardId" : "{cardId}"
}
|
Item Update
1
| [POST] /api/items/{itemId}
|
1
2
3
| {
"cardId" : "{cardId}"
}
|
Item Delete
1
| [DELETE] /api/items/{itemId}
|
1
2
3
| {
"cardId" : "{cardId}"
}
|
History API
History Read
1
2
3
| {
"cardId" : "{cardId}"
}
|
- History의 create는 서버에서 모든 api가 호출될 때 마다 호출되도록 구현
- History의 update/delete는 불가능하도록 구현
히스토리는 사용자가 직접 만들지 않고 다른 API가 호출될 때 서버가 남기는 기록이라 조회 API만 공개한다. 기록을 고치거나 지울 수 없게 하면 변경 이력을 감사 로그처럼 믿고 쓸 수 있다.
설계 관례로 보면 수정은 PUT(전체 교체)이나 PATCH(부분 수정)를 쓴다. Card Update는 PUT인데 Item Update는 POST로 적혀 있어, 구현할 때 하나로 맞춰야 할 부분이다.
설계할 때 참고한 원칙
REST API design with Spring
Spring 공식 가이드다. 첫 번째는 @RestController와 @GetMapping으로 JSON을 돌려주는 가장 작은 서비스를 만든다. 두 번째 튜토리얼은 직원 관리 예제를 HTTP 메서드별 엔드포인트로 확장하고, Spring HATEOAS로 응답에 관련 링크를 넣어 클라이언트가 URI를 하드코딩하지 않게 하는 단계까지 다룬다.
RESTful URL design
URI는 리소스를 명사로 나타내고 행위는 메서드로 표현한다. restfulapi.net의 리소스 이름 가이드는 문서(단일 리소스)는 단수, 컬렉션은 복수 명사를 쓰고, 계층은 /로 표현하며, 소문자와 하이픈을 쓰고, URI에 CRUD 함수 이름을 넣지 말라고 정리한다. 위 API의 /api/cards, /api/cards/{cardId}가 이 규칙을 따른 형태다.
API Documentation
API 문서에는 엔드포인트, 메서드, 요청 파라미터와 본문, 응답 형식과 상태 코드, 예시가 들어가야 한다. Postman은 컬렉션에 저장한 요청을 바탕으로 문서를 만들어 공유할 수 있고, Swagger(OpenAPI)는 API를 명세 파일로 기술해 문서 화면과 클라이언트 코드를 생성한다. 손으로 쓴 문서는 코드와 어긋나기 쉬워서, 명세나 테스트에서 문서를 생성하는 방식이 유지보수에 유리하다.
참고한 자료외부 출처 9
댓글
아직 댓글이 없습니다