REST API 설계시 가장 흔하게 하는 실수 5가지 와 그 해결 방법

REST API는 최신 소프트웨어 아키텍처의 필수적인 부분이다. 이는 서로 다른 시스템이 원활하게 통신하고 데이터를 교환할 수 있도록 해준다. 하지만 잘 설계된 API를 만드는 것은 생각보다 복잡할 수 있다. 개발자들이 흔히 저지르는 몇 가지 실수가 있으며, 이는 비효율적이고 안전하지 않으며 확장하기 어려운 API로 이어질 수 있다.

이 글에서는 가장 흔한 REST API 설계 실수 5가지와 이를 피하는 방법을 알아본다.

1. 동사를 사용한 엔드포인트 경로

REST API를 설계할 때 흔히 저지르는 실수 중 하나는 엔드포인트 경로에 동사를 사용하는 것이다. REST 원칙에 따르면, 엔드포인트 경로는 리소스를 나타내야 하며, 이는 명사로 표현되어야 한다. 수행할 작업은 HTTP 메서드(GET, POST, PUT, DELETE 등)로 지정해야 한다.

예를 들어, 새 사용자를 생성하는 엔드포인트를 만든다고 가정해 보자. 동사를 사용하는 잘못된 접근 방식은 다음과 같을 것이다:

POST /createUser

대신, 올바른 접근 방식은 'users' 리소스를 나타내는 명사를 사용하고, 작업을 나타내기 위해 HTTP POST 메서드를 사용하는 것이다:

POST /users

마찬가지로, 특정 사용자의 정보를 검색하려면 다음을 사용한다:

GET /users/{id}

사용자 정보를 업데이트하려면 다음을 사용한다:

PUT /users/{id}

그리고 사용자를 삭제하려면 다음을 사용한다:

DELETE /users/{id}

항상 명사를 사용하여 리소스를 표현하고, HTTP 메서드를 사용하여 해당 리소스에 대한 작업을 표현하는 것을 기억하자.

2. 일관성 없는 네이밍 컨벤션

일관성 없는 네이밍 컨벤션은 API를 사용하기 어렵고 혼란스럽게 만들 수 있다. 이는 엔드포인트 경로, JSON 속성, 쿼리 파라미터 등 API의 모든 측면에 적용된다.

예를 들어, 어떤 엔드포인트에서는 camelCase를 사용하고 다른 엔드포인트에서는 snake_case를 사용하는 것을 피해야 한다. 하나의 컨벤션을 정하고 API 전체에서 일관되게 사용해야 한다.

다음은 JSON 속성에 대한 일관성 없는 네이밍의 예이다:

{
  "firstName": "Milan",
  "last_name": "Jovanovic"
}

더 나은 접근 방식은 camelCase와 같은 하나의 컨벤션을 고수하는 것이다:

{
  "firstName": "Milan",
  "lastName": "Jovanovic"
}

마찬가지로, 엔드포인트 경로에 복수형 명사를 사용할지 단수형 명사를 사용할지 결정하고 이를 일관되게 지켜야 한다. 일반적으로 컬렉션을 나타내기 위해 복수형 명사(users 대신 user)를 사용하는 것이 좋다.

3. 부적절한 HTTP 상태 코드 사용

HTTP 상태 코드는 API 응답의 결과를 나타내는 필수적인 부분이다. 이는 클라이언트에게 요청이 성공했는지, 실패했는지, 아니면 다른 조치가 필요한지를 알려준다. 부적절한 상태 코드를 사용하면 클라이언트가 응답을 잘못 해석하여 예기치 않은 동작을 유발할 수 있다.

예를 들어, 클라이언트가 잘못된 데이터를 제공하여 요청이 실패한 경우 500 Internal Server Error를 반환해서는 안 된다. 대신 400 Bad Request를 반환해야 한다.

다음은 몇 가지 일반적인 HTTP 상태 코드와 그 의미이다:

• 200 OK: 요청이 성공했다.
• 201 Created: 요청이 성공했고 결과적으로 새 리소스가 생성되었다.
• 204 No Content: 요청이 성공했지만 반환할 콘텐츠가 없다.
• 400 Bad Request: 서버가 클라이언트 오류(예: 잘못된 구문)로 인해 요청을 처리할 수 없다.
• 401 Unauthorized: 요청에 유효한 인증 자격 증명이 부족하다.
• 403 Forbidden: 서버가 요청을 이해했지만 승인을 거부했다.
• 404 Not Found: 서버가 요청한 리소스를 찾을 수 없다.
• 500 Internal Server Error: 서버에 예기치 않은 조건이 발생하여 요청을 이행할 수 없다.

항상 응답의 결과에 맞는 적절한 HTTP 상태 코드를 사용하자.

4. 응답에 너무 많거나 적은 데이터 반환

잘 설계된 API는 클라이언트가 필요로 하는 정확한 양의 데이터를 반환해야 한다. 너무 많은 데이터를 반환하면(오버페칭) 불필요한 네트워크 트래픽과 클라이언트의 느린 처리로 이어질 수 있다. 반면에 너무 적은 데이터를 반환하면(언더페칭) 클라이언트가 필요한 정보를 얻기 위해 추가 API 호출을 해야 하므로 대기 시간이 늘어날 수 있다.

예를 들어, 사용자 목록을 반환하는 엔드포인트가 있다고 가정해 보자. 각 사용자에 대한 모든 필드를 반환하는 대신, 클라이언트가 표시해야 하는 필드(예: id, name, email)의 하위 집합만 반환하는 것을 고려해야 한다.

오버페칭과 언더페칭을 모두 피하는 한 가지 방법은 클라이언트가 fields 쿼리 파라미터를 사용하여 요청하는 필드를 지정할 수 있도록 하는 것이다.

GET /users?fields=id,name,email

GraphQL은 또한 클라이언트가 필요한 데이터를 정확하게 요청할 수 있도록 하여 이 문제를 해결하기 위한 훌륭한 솔루션이다.

5. 기본적인 보안 조치 무시

보안은 API 설계에서 가장 중요한 측면 중 하나이다. 기본적인 보안 조치를 무시하면 API가 무단 액세스, 데이터 유출 및 기타 취약점에 노출될 수 있다.

다음은 몇 가지 필수적인 보안 모범 사례이다:

• HTTPS 사용: 항상 HTTPS를 사용하여 클라이언트와 서버 간에 전송되는 데이터를 암호화하여 도청 및 중간자 공격을 방지해야 한다.
• 인증 및 인가 구현: 인증(누가 당신인지 확인) 및 인가(무엇을 할 수 있는지 확인) 메커니즘을 구현하여 API를 보호해야 한다. 일반적인 솔루션으로는 OAuth 2.0, JWT(JSON Web Tokens), API 키 등이 있다.
• 입력 유효성 검사: SQL 인젝션, XSS(Cross-Site Scripting) 및 기타 공격을 방지하기 위해 항상 클라이언트의 입력을 유효성 검사해야 한다.
• 속도 제한 구현: API 남용을 방지하고 모든 사용자에 대해 공정한 사용을 보장하기 위해 속도 제한을 구현해야 한다.

보안은 지속적인 프로세스이며, 새로운 위협이 등장함에 따라 항상 경계를 늦추지 않고 보안 조치를 업데이트해야 한다.