REST API URL 규칙

리소스 명사는 복수형으로

# Good
/language-tests

# Bad
/language-test

URL에 kebab-case 사용, parameter에 camelCase 사용

# Good
/language-tests
/language-tests/{testId}

# Bad
/language_tests/{test-id}
/languageTests/{test_id}

리소스 URL에 동사 금지

# Good
POST /language-tests

# Bad
POST /language-tests/create

단, CRUD 작업이 아닌 경우에는 동사 사용 가능

POST /language-tests/123/revalidate

리소스 리스트에는 리소스 갯수 포함

GET /language-tests

# Response
{
		languageTests: [
			...
		],
		total: 42
}

PUT vs. PATCH

둘의 역할은 모두 업데이트로 같지만, PATCH는 제공된 필드만 업데이트하고 나머지는 그대로 유지합니다.

Nested resource

GET /posts/2/comments
DELETE /posts/2/comments/3

위와 같이 중첩된 리소스를 표현할 수 있습니다.

이때, 리소스를 nested로 표현할지, flat하게 표현할지 고민이 될 수 있습니다.

# Nested
GET /posts/2/comments/3
# Flat
GET /comments/3

각 방법마다 trade-off가 존재하겠지만, 어떤 방법을 선택할지 고민이 된다면 대부분 flat 한것이 nested보다 낫다는 것을 기억해야합니다.

다수의 리소스 생성/수정/삭제

POST /posts/batch 와 같은 API endpoint를 만들어 사용한다.

이때 GET 대신 POST를 사용하는 이유는 GET에는 body를 사용할 수 없기 때문이다. 또한 한 요청에 여러 GET, POST, PATCH등이 들어갈 수 있기에 멱등성을 지키지 않는 POST를 쓰는게 일반적이다. 배치 요청 자체가 RESTful API에 크게 부합하는 구조는 아니니 RESTful API 원칙을 너무 신경쓰지 않아도 좋아 보인다.

RFC 7231상 GET에도 body를 담을 수 있으나, 실질적으로 이를 구현하는 프로그램이 별로 없다

 

고민해보아야 할 부분은, 일부 실패시 전체 트랜잭션을 취소할것인지 여부나 최대 배치 작업 개수 한도등이 있겠다.

Reference

[번역] 22 Best Practices to Take Your API Design Skills to the Next Level

[번역] 22 Best Practices to Take Your API Design Skills to the Next Level

https://www.codementor.io/blog/batch-endpoints-6olbjay1hd

Adding batch or bulk endpoints to your REST API