인터페이스(Interface)란? 인터페이스 정의서로 협업하기

인터페이스는 백엔드와 프론트엔드가 소통하기 위한 규약이라고 생각하면 된다. 백엔드는 데이터를 처리하고 비즈니스 로직을 구현하며 서버와의 통신을 담당한다. 이러한 백엔드의 기능들은 프론트엔드에 정보와 기능을 제공하는 데 사용된다.

 

인터페이스는 일종의 계약서다. 이 계약서에는 백엔드가 어떤 데이터를 제공하고 어떤 기능을 제공하는지에 대한 설명이 포함된다. 프론트엔드 개발자는 이 계약서를 참고하여 필요한 데이터나 기능을 요청하고, 그에 맞는 방식으로 백엔드와 소통한다.

 

더 구체적으로 예를 들어 설명하면, 백엔드에서는 특정 API를 제공하며, 프론트에서는 이 API를 통해 데이터를 요청하거나 서버에 특정 작업을 요청할 수 있다. 이때 API의 형식이나 파라미터, 응답 형식 등이 인터페이스의 일부가 된다. 프론트엔드 개발자는 백엔드의 인터페이스를 이해하고 해당 API를 호출하거나 데이터를 요청함으로써 필요한 정보를 얻거나 작업을 수행할 수 있다.

 

반응형

 

인터페이스 정의서

일반적으로 인터페이스 정의서는 백엔드 개발자가 작성하여 프론트엔드 개발자 또는 다른 팀원들에게 전달한다. 인터페이스 정의서는 백엔드 개발자가 API의 명세와 기능을 명확하게 정의하고 문서화하여 다른 팀원들이 이를 이해하고 활용할 수 있도록 돕는 역할을 한다.

백엔드 개발자는 자신이 개발한 API의 엔드포인트, 요청 형식, 응답 형식, 파라미터, 응답 상태 코드 등을 정확히 기술하고 문서화해야 한다. 이렇게 작성된 인터페이스 정의서를 프론트엔드 개발자에게 제공함으로써 백엔드와 프론트엔드 간의 원활한 소통과 협업이 가능해진다.

따라서 인터페이스 정의서는 백엔드 개발자들이 작성하여 다른 팀원들에게 전달하는 중요한 문서라고 볼 수 있다.

 

인터페이스 정의서는 일반적으로 다음과 같은 정보를 포함할 수 있다.

• API 엔드포인트와 HTTP 메서드: 백엔드가 제공하는 각 API의 엔드포인트 경로와 해당 API를 호출하기 위해 사용해야 하는 HTTP 메서드(GET, POST, PUT, DELETE 등)를 명시한다. 예를 들어, /login 경로에 POST 요청을 보내면 로그인이 처리되는 API라면 해당 정보를 정의한다.
• 요청과 응답의 데이터 형식: 백엔드와 프론트엔드 간의 데이터 교환 형식을 정의한다. 예를 들어, 요청과 응답에 JSON 형식을 사용한다면, JSON 객체의 필드와 그 형식을 명시한다.
• 파라미터: 각 API에 필요한 파라미터와 그에 대한 설명을 포함한다. 파라미터는 API 호출 시에 전달되는 데이터로, 예를 들어 로그인 API에서는 사용자명과 비밀번호가 필요한데, 이러한 파라미터들을 정의한다.
• 응답 상태 코드: 백엔드에서 API 호출에 대한 응답으로 반환하는 상태 코드를 설명한다. 예를 들어, 성공적인 응답에는 200 OK 상태 코드를 사용하고, 인증 오류에는 401 Unauthorized 상태 코드를 사용할 수 있다.
• 에러 처리: API 호출 시 발생할 수 있는 예외 상황과 에러 처리 방법을 설명한다. 예를 들어, 유효하지 않은 요청이 들어올 경우 어떤 상태 코드를 반환하고 어떤 에러 메시지를 제공해야 하는지를 정의한다.

 

인터페이스 정의서 관리

아래 표에는 API의 엔드포인트, HTTP 메서드, 요청 파라미터, 응답 데이터 형식, 그리고 응답 상태 코드 등을 열과 행으로 구성하여 정리되어 있다. 이렇게 작성된 인터페이스 정의서를 엑셀로 관리하면 정보를 쉽게 확인하고 업데이트할 수 있다.

 

API 엔드포인트	HTTP 메서드	요청 파라미터	응답 데이터 형식	응답 상태 코드
/users	GET	-	JSON	200: 성공, 404: 사용자 없음
/users/{id}	GET	id (파라미터 타입: 정수)	JSON	200: 성공, 404: 사용자 없음
/users	POST	JSON 객체	-	201: 생성됨, 400: 잘못된 요청
/users/{id}	PUT	id (파라미터 타입: 정수)	JSON 객체	200: 성공, 404: 사용자 없음, 400: 잘못된 요청
/users/{id}	DELETE	id (파라미터 타입: 정수)	-	204: 삭제됨, 404: 사용자 없음, 400: 잘못된 요청

이 외에도 인터페이스 정의서는 다양한 형식으로 관리될 수 있다. 그중에서도 Swagger는 인기 있는 도구 중 하나이다.

Swagger는 API 문서를 작성하고 관리하기 위한 프레임워크로, 개발자들이 API에 대한 정보를 문서화하고 시각적으로 확인할 수 있도록 도와준다. Swagger를 사용하면 API의 엔드포인트, 요청 및 응답 형식, 파라미터, 응답 상태 코드 등을 정의하고 문서화할 수 있다. Swagger를 활용하면 자동으로 API 문서를 생성하고 인터랙티브 한 방식으로 사용할 수 있는 UI를 제공해 준다.

뿐만 아니라, 다른 형식으로는 Markdown이나 HTML 문서로 작성하여 관리하기도 한다. Markdown은 간단하고 가독성이 좋은 문서 형식이며, HTML은 더욱 정교한 포맷팅과 스타일링을 제공할 수 있다.

어떤 형식을 선택할지는 개발자의 선호도와 팀의 요구사항에 따라 다를 수 있다. Swagger는 많은 개발자들에게 인기가 있으며, API 문서를 표준화하고 관리하기에 효과적인 도구로 사용된다. 하지만 직접 문서를 작성하는 것도 일반적인 방법이다. 형식보다 중요한 점은 인터페이스 정의서가 명확하고 업데이트되며, 팀원들이 쉽게 접근하고 이해할 수 있는 형식으로 관리되어야 한다는 것이다.

 

인터페이스를 통한 협업

위의 인터페이스 정의서를 기반으로 백엔드와 프론트엔드가 소통하고 작업하는 과정을 예시 코드를 통해 살펴보자.

 

1) 백엔드 개발자는 인터페이스 정의서를 작성한다. 이를 통해 백엔드 개발자는 API의 엔드포인트, HTTP 메서드, 요청 파라미터, 응답 데이터 형식, 응답 상태 코드 등을 정확히 명시한다.

2) 프론트엔드 개발자는 백엔드 개발자가 작성한 인터페이스 정의서를 받아 확인한다. 이를 통해 어떤 API가 제공되는지, 요청과 응답의 형식은 어떤지 등을 파악할 수 있다.

fetch('/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: '사용자명',
    password: '비밀번호',
  }),
})
  .then(response => response.text())
  .then(data => {
    // 로그인 요청에 대한 응답 처리
    console.log(data);
  })
  .catch(error => console.error(error));

3) 프론트엔드 개발자는 인터페이스 정의서를 참고하여 실제로 API를 호출하고 요청을 보낸다. 예를 들어, 프론트엔드에서 로그인 기능을 구현하기 위해 /login 경로에 POST 요청을 보낼 수 있다. 로그인에 필요한 사용자명과 비밀번호를 JSON 형식으로 전송하고, 이후 응답을 받아와 처리한다.

4) 백엔드에서 로그인 요청 처리하기: 백엔드에서는 /login 경로에 대한 POST 요청에 대한 처리를 수행한다. 해당 메서드는 받아온 사용자 정보를 검증하고 인증 과정을 수행한 뒤, 결과에 따라 적절한 응답을 반환한다.

@RestController
public class AuthController {

    @PostMapping("/login")
    public ResponseEntity<String> login(@RequestBody LoginRequest request) {
        // 받아온 사용자 정보를 검증하고 인증 과정을 수행하는 코드
        // ...

        if (isValidCredentials(request.getUsername(), request.getPassword())) {
            // 인증이 성공한 경우 토큰을 생성하거나 세션을 유지하는 등의 작업을 수행하는 코드
            // ...

            return ResponseEntity.ok("로그인 성공");
        } else {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("로그인 실패");
        }
    }

    // 다른 백엔드 기능들과 관련된 API들도 정의할 수 있음
    // ...
}

5) 프론트엔드 개발자는 백엔드로부터 받은 응답을 처리한다. 예를 들어, 로그인 요청에 대한 응답으로 성공적인 로그인인지, 실패인지를 확인하고, 그에 따른 다음 동작을 수행한다.

 

이와 같은 방식으로 프론트엔드와 백엔드는 인터페이스 정의서를 확인하고 작업을 진행함으로써 상호 간에 정확한 소통과 원활한 협업을 이루어낼 수 있다. 인터페이스 정의서는 두 팀 사이의 협업을 간소화하고 개발 작업의 일관성과 효율성을 향상하는 중요한 문서라고 볼 수 있다.