댓글 검색 목록

[Nodejs] REST API 설계를 위한 9 가지 모범 사례

페이지 정보

작성자 운영자 작성일 20-11-13 15:26 조회 668 댓글 0

많은 경우에 우리는 REST API를 개발할 때 (또는 이 패턴을 가지려고 시도 할 때) 깨끗하고 이해하기 쉬우며 확장 가능한 아키텍처를 설정하는 것의 중요성을 중요하게 생각하지 않지만 장기적으로는 애플리케이션이 성장함에 따라 큰 영향을 미칩니다.

우리가 개발하고 있는 인터페이스를 사용자에게 공개 할 때가 왔다고 가정 해 보겠습니다. 사용자가 인터페이스에서 전송하려는 것과 동일한 내용을 이해하고 있다는 확신이 있습니까? 응용 프로그램을 사용하는 사용자에 대한 이해는 관련이 있을 뿐만 아니라 응용 프로그램을 사용하게 될 팀과 미래의 사람들에게도 이해할 수 있습니다. 처음부터 모두가 존중할 아키텍처를 구축하는 것이 중요합니다.

고려해야 할 가장 중요한 몇 가지 측면은 다음과 같습니다.

1. HTTP 메소드를 사용하여 엔드 포인트에 의미 부여

REST API는 애플리케이션의 각 CRUD 작업에 대해 HTTP 메서드를 사용하도록 권장합니다. 그중 GET, POST, PUT, DELETE 및 PATCH의 다양성이 있습니다. 리소스와 연결된 끝점의 이름은 적용된 작업과 관련된 HTTP 메서드와 함께 제공되어야 합니다.

- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
+ GET /cats
+ POST /cats
+ PUT /cats
+ DELETE /cats

2. 상태 코드는 API 결과에 따라야 합니다.

애플리케이션의 가장 중요한 특성 중 하나는 엔드 포인트의 반환이 해당 상태 코드와 관련되어 있다는 것입니다. 이것은 우리의 결과가 성공하거나 실패하는 순간 우리가 전달하고자 하는 메시지를 보다 설명적인 방식으로 연결할 수 있음을 의미합니다.

예를 들어, 상태가 200이면 결과가 성공했음을 즉시 알 수 있습니다. 그렇지 않으면 상태 400이 되면 결과가 실패합니다.

반환 메시지가 일부 상태 코드와 잘못 연관되어있는 경우가 발생할 수 있으므로 (매우 일반적이며) 기존 상태 코드를 알고 각각을 적용해야 하는 경우를 아는 것이 중요합니다. REST API의 개발자와 소비자 사용자에게 혼란을 야기하기 때문입니다.

// Bad, we return status code 200 (Success)
// associated with an error object
{
    "status": 200,
    "error": {...}
}

// Good
{
    "status": 200,
    "data": [...]
}

3. 필터, 정렬 및 페이지 매김 지원

API를 사용하는 모든 애플리케이션의 많은 경우 성능, 검색 시스템, 정보가 과도하거나 리소스에서 특정 항목을 표시하는 것처럼 간단하기 때문에 어떤 식으로든 서비스에서 리소스를 적게 사용하기를 원할 것입니다.

API의 기능을 확장하는 것 외에도 필터링, 정렬 및 페이지 매김은 서버의 리소스 소비를 줄이는 데 도움이 됩니다.

수백만 개의 결과를 반환하는 엔드 포인트의 경우를 상상해 봅시다. 서버는 어떻게 반응할까요? (그는 분명히 울고 쓰러 질 것입니다 ?).

GET / cats? race = misumisu & age = 1-> 필터링, 다음 속성을 가진 모든 고양이 검색 : race is misumisu, the age is 1
GET / cats? limit = 15 & offset = 0-> 페이지 매김, 0 행부터 시작하여 15 행을 반환합니다.
GET / cats? sort_by = name & order_by = asc-> 정렬, 오름차순으로 정렬 된 행을 반환합니다.

4. Plural endpoints

다양한 API 개발과 관련하여 제가 매일 접하는 토론 중 하나는 엔드 포인트 구성에 단수 또는 복수를 사용할지 여부를 결정하는 것입니다. 요컨대, 우리는 애플리케이션에서 견고한 일관성을 유지하기를 원하며,이를 위해 엔드 포인트를 복수로 구축하는 것이 좋습니다.

리소스가 항상 단일 결과를 갖는 것은 아니며 테이블에 많은 결과가 있을 수 있으며 하나만 있는 경우에도 단일로 배치하더라도 경로 이름 형식에서 일관성을 유지하지 않습니다.

“일관성은 성공의 열쇠입니다.”?

- GET /cat
- GET /cat/:id
+ GET /cats
+ GET /cats/:id

5. 리소스 이름으로 엔드 포인트 이름 지정

일관성에 대해 말하자면, 경로가 리소스에 대한 작업을 처리하는 역할을 한다는 것을 알고 있다면 리소스 이름으로 직접 이름을 지정하는 것이 중요하므로 사람이 API를 사용할 때 작업 중인 엔터티를 이해하게 됩니다. 의 위에.

예를 들어 고양이를 반환 할 경우 엔드 포인트 / dogs ?를 호출하지 않습니다.

6. Resource hierarchy

리소스에 속한 밀접하게 연결된 엔터티에 액세스하려면 어떻게 해야 합니까?

이 관계를 표시하기 위해 두 가지 옵션이 있습니다.

작성자 엔드 포인트에 계층 적으로 기사 추가
쿼리 문자열

"저자"와 "기사"의 전형적인 예를 들어 보겠습니다.

GET /authors/betoyanes/articles/create_cat_memes
GET /articles?author=betoyanes&name=create_cat_memes

이러한 방법은 유효하며 많은 프로젝트에서 이를 보았습니다. 개인적으로 현재 경로를 확장하는 것보다 쿼리 문자열을 사용하는 것이 더 깔끔하다고 생각합니다. 애플리케이션이 확장 될수록 우리는 확실히 더 큰 계층 구조를 갖게 될 것이며 차례로 경로가 확장 될 것입니다. 그럼에도 불구하고 각 사람의 기준에 따라 다르므로 가장 선호하는 것을 사용하십시오!

7. 버전 관리

우리가 개발함에 따라 오류가 없고 방탄이 되는 API의 안정적이고 확실한 버전을 갖는 것은 불가피합니다. API를 배포하고 여러 클라이언트가 이를 사용하기 시작한다고 가정 해 보겠습니다. 리소스에서 더 많은 데이터를 추가하거나 제거해야 하는 시점에서 어떤 일이 발생합니까? 인터페이스를 사용하는 외부 서비스에서 버그를 생성 할 수 있습니다. 그렇기 때문에 우리 애플리케이션에 대한 버전 관리 메커니즘이 필수적입니다.

여러 가지 방법이 있지만, 저는 엔드 포인트에 경로의 버전을 명시 적으로 포함 할 버전이 지정된 URI의 팬입니다.

// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs

8. Caching

API 속도를 높이고 리소스 소비를 줄이는 강력한 도구 중 하나는 캐싱이며, 동일한 결과가 계속 발생하면 데이터베이스에 동일한 요청을 여러 번 요청하지 않는 것이 아이디어입니다. 이 시스템을 구현하는 데 도움이 될 수 있는 몇 가지 서비스가 있습니다. 그중 제가 가장 좋아하는 서비스 중 하나는 Redis입니다.

우리는 캐시 된 기능을 구현하는 데 일반적으로 비용이 발생한다고 들었습니다. 이것이 예외는 아닙니다. 다음과 같은 질문을 하겠습니다. 정보가 동적입니까 아니면 정적입니까? 동적 인 경우 정보가 얼마나 자주 변경됩니까?

? 캐시에 정보가 오래 보관되어 있다는 사실을 인지하는 것이 중요합니다. 이는 정보를 장기간 보관함으로써 API의 잘못된 결과를 초래할 수 있으므로 캐시의 기간을 짧게 유지하는 것이 좋습니다.

9. 문서

우리의 최고의 무기 중 하나이며 많은 사람들이 가장 싫어하는 것은 문서입니다. 이러한 맥락에서 문서화 된 API는 이를 사용하는 사용자가 접근성, 응답, 요청, 예제를 포함하여 인터페이스의 몇 가지 중요한 측면을 이해할 수 있도록 필수적입니다.

접근성 : 인터페이스의 위치와 액세스는 가장 중요한 특성 중 하나이며 고객에게 how_to_use.txt를 제공하고 싶지 않습니다. 모든 사람이 볼 수 있는 클라우드에 문서를 노출하는 것이 우리가 할 수 있는 가장 편리한 일입니다.
응답 및 요청 : 우리가 제공하는 정보는 모든 자원이 생성 할 수 있는 가능한 모든 결과와 이를 소비하는 방법을 고려해야 합니다.
Examples : 콘솔에서 실행하고 응답을 받을 수 있는 bash 스크립트 인 경우에도 인터페이스를 사용할 수 있는 방법에 대한 예제를 제공하는 것은 매우 중요합니다.

결론

API는 백엔드 서비스를 사용하기 위해 노출하는 인터페이스이므로이를 염두에 두고 이를 사용하고 작업하는 사람들이 원하는 대로 되도록 최상의 원칙을 적용하는 것이 중요합니다.

개인 프로젝트를 개발하고 있지만 우리가 고려하는 최상의 원칙을 적용하여 개발 팀이나 프로젝트에 들어갈 때 연습을 할 수 있도록 해야 합니다.