REST API 개선 사례

이전 회사에서 레거시 API를 REST하게 바꾸려는 노력을 했었는데요, 실제 코드를 보면서 확인해 보겠습니다.
아래는 훈련인증서(Certificate)를 CRUD 하고 훈련인증서를 고객의 이메일로 전송해주는 API들입니다.
API URL 코드는 PHP/Laravel 을 기반으로 만들어졌습니다.

Before (개선전)

Before 코드를 확인해보면, 다음과 같은 점이 잘못됐다고 볼 수 있습니다.
1. URI에 자원에 대한 행위가 포함 되어 있다. (update, edit, show, delete)
2. /certificate-edit은 자원에 대한 행위가 Edit인데, HTTP Method는 GET으로 구현이 되어 있다.
3. 마지막줄의 Route::post('/certificate', 'CertificateController@sendMailCertificate'); 같은 경우에는 고객에게 Mail을 보내는 API인데 URI만 보아서는 어떤 동작을 하는지 추론하기 어렵고, 오히려 certificate를 create 하거나 update 하는 행위로 보여진다.
4. 복수형을 사용하기보다 단수형을 사용했다.
5. /certificate-update, /certificate-edit이 서로 어떤 다른 동작을 하는지 알 수 없다.

After (개선후)

개선은 위의 잘못된 점을 바탕으로 진행하였습니다.

[POST] /certificate-update => [PUT] /certificates -> Admin의 인증서 생성 또는 업데이트 하는 API
[GET] /certificate-show => [GET] /certificates -> Admin의 인증서 정보를 가져오는 API
[DELETE] /certificate-delete => [DELETE] /certificates -> Admin의 인증서를 지우는 API
[POST] /certificate => [POST] /users/{user_id}/send-mail -> Admin에게 속한 {user_id}에게 Admin의 훈련 인증서를 전송하는 API

이제 REST API라고 부를 수 있을까?

개선 후의 코드는 확실하게 개선전의 코드보다 REST API 설계 원칙을 잘 따르고 있다고 보여집니다.
이제 REST API라고 부를 수 있을까요?

REST 제약조건들 중 가장 지켜지지 않는 것은 Uniform Interface인데, 이중에서도 self-descriptive messages와 HATEOAS가 가장 지켜지지 않는다고 합니다.
[GET] /certificates 를 Postman을 활용해 직접 호출한 뒤 self-descriptive messages와 HATEOAS를 따져보겠습니다.

BODY

HEADER

Self-descriptive

1. Response Header의 Content-Type을 확인하여 media type(application/json)을 알 수 있습니다.
2. 명세에는 json 문서가 나타나있기 때문에 json 문서를 파싱하는데 성공합니다.
3. 하지만 Body의 "id", "client_id", "type"등 키값이 무엇을 의미하는지 알 수 없습니다.
4. 결론적으로 Self-descriptive 하지 못하기 때문에 완벽한 REST API가 아닙니다. ❌

HATEOAS

1. HATEOAS 원칙에 따라서 다음 상태로 전이할 링크를 찾습니다.
2. 전이할 링크가 JSON response안에 포함 되어 있지 않습니다.
3. 결론적으로 HATEOAS 원칙을 지키지 못했기 때문에 완벽한 REST API가 아닙니다. ❌

꼭 Self-descriptive와 HATEOAS를 지켜야 하는가?

로이 필딩은 REST의 제약조건을 한개라도 지키지 않는다면 REST API라고 부를 수 없다고 본인이 직접 밝혔습니다.
우리는 Self-descriptive와 HATEOAS를 포함한 REST 제약조건을 정확히 지킨 REST API를 만들지, 아니면 구색만 갖춘, 사실 REST API가 아닐지도 모르는 API를 설계하고 REST API라고 부를지 정해야할 것 같습니다.
사실 대부분의 서비스에서는 암묵적으로 Self-descriptive와 HATEOAS가 빠져도 REST API라고 칭하고 있는 것 같습니다.
그럼에도 로이필딩은 이러한 API를 REST API가 아닌 HTTP API 라고 불리길 바랍니다.

꼭 REST API 여야만 하는가? (REST API의 단점)

로이필딩은 시스템 전체를 통제할 수 있다고 생각하거나 진화에 관심이 없다면 REST에 대해 따지느라 시간을 낭비하지 말라고 했습니다.
그리고 REST에는 다음과 같은 단점들이 존재합니다.

✅ 1. 안티패턴으로 설계될 가능성

REST API에 대해 이해도가 떨어질 경우 구색만 갖춘, REST 사상에 어긋나는 API를 설계할 수도 있는 가능성이 있습니다.

✅ 2. 표준 규약이 없는 점

사실 REST는 표준이 없습니다. REST 아키텍처는 사실 암묵적인 규칙(Defector reference)이며, 이로 인해 안티패턴의 형태로 발전하는 경향도 커지고 있습니다.

✅ 3. RDBMS의 표현에 적합하지 않은 점

RDBMS는 다양한 키들이 존재하는데, REST API는 리소스를 표현할 때 나열하기 용의한 형태(ex: JSON)를 사용하기에 RDBMS에는 표현이 적합하지 않을 수도 있습니다.

이러한 단점들을 개선한 통신 규약으로는 GraphQL이 있습니다.
하지만 아직까지는 REST API가 더 많이 사용되며, GraphQL도 장단점이 명확히 존재하니 상황에 맞춰 적절한 통신 규약을 선택해야 합니다.

끝으로

REST API는 HTTP 통신을 기반으로 하는 개발에서 정말 중요하다고 생각합니다.
이번 블로그 글의 작성 겸험을 바탕으로 REST API를 REST 원칙에 어긋나지 않도록 설계할 수 있을 것 같습니다 🙆🏻‍♂️
이 글은 아주 유명한 영상인 그런 REST API로 괜찮은가(https://www.youtube.com/watch?v=RP_f5dMoHFc)의 영향을 많이 받았습니다.