변화에 대한 전망을 가지고 외부 애플리케이션을위한 API를 설계하는 것은 쉽지 않지만, 조금만 생각하면 나중에 인생을 더 쉽게 만들 수 있습니다. 이전 버전 처리기를 그대로 두어 이전 버전과의 호환성을 유지하면서 향후 변경 사항을 지원할 계획을 세우려고합니다.
이 기사의 주요 관심사는 주어진 제품 / 회사에 대해 정의 된 모든 엔드 포인트에 대해 어떤 패턴을 따라야 하는가입니다.
기본 체계
의 기본 URL 템플릿을 감안할 때 https://rest.product.com/모든 서비스 /api가 /auth와 같은 기타 비 기반 엔드 포인트와 함께 존재하도록 고안했습니다 /doc. 따라서 다음과 같이 기본 엔드 포인트를 설정할 수 있습니다.
https://rest.product.com/api/...
https://rest.product.com/auth/login
https://rest.product.com/auth/logout
https://rest.product.com/doc/...
서비스 엔드 포인트
이제 엔드 포인트 자체를 위해. 우려에 대해 POST, GET, DELETE이 문서의 주요 목적하지 않고 이러한 작업 자신의 관심사입니다.
엔드 포인트는 네임 스페이스와 작업으로 분류 될 수 있습니다. 각 조치는 리턴 유형 또는 필수 매개 변수의 근본적인 변경을 지원하는 방식으로 제시되어야합니다.
등록 된 사용자가 메시지를 보낼 수있는 가상 채팅 서비스를 사용하면 다음과 같은 엔드 포인트가있을 수 있습니다.
https://rest.product.com/api/messages/list/{user}
https://rest.product.com/api/messages/send
이제 향후 API 변경에 대한 버전 지원을 추가하여 중단 될 수 있습니다. 이후 /api/또는 이후에 버전 서명을 추가 할 수 있습니다 /messages/. send엔드 포인트가 주어지면 v1에 대해 다음을 가질 수 있습니다.
https://rest.product.com/api/v1/messages/send
https://rest.product.com/api/messages/v1/send
첫 번째 질문은 버전 식별자의 권장 장소는 무엇입니까?
컨트롤러 코드 관리
이제 이전 버전을 지원해야하므로 시간이 지남에 따라 더 이상 사용되지 않을 수있는 각각의 새 버전에 대한 코드를 처리해야합니다. Java로 엔드 포인트를 작성한다고 가정하면 패키지를 통해이를 관리 할 수 있습니다.
package com.product.messages.v1;
public interface MessageController {
void send();
Message[] list();
}
이는 모든 코드가 네임 스페이스를 통해 분리되어 변경 사항이 변경되면 서비스 엔드 포인트의 새 사본이됨을 의미합니다. 이것의 단점은 모든 코드를 복사해야하며 버그 수정을 새로운 버전과 이전 버전에 적용하기를 원할 때마다 각 사본마다 적용 / 테스트해야한다는 것입니다.
다른 방법은 각 엔드 포인트에 대한 핸들러를 작성하는 것입니다.
package com.product.messages;
public class MessageServiceImpl {
public void send(String version) {
getMessageSender(version).send();
}
// Assume we have a List of senders in order of newest to oldest.
private MessageSender getMessageSender(String version) {
for (MessageSender s : senders) {
if (s.supportsVersion(version)) {
return s;
}
}
}
}
이제는 각 엔드 포인트 자체에 대한 버전 관리를 분리하고 대부분의 경우 한 번만 적용하면되는 버그 수정 포트 호환 문제를 해결할 수 있지만,이를 지원하려면 각 개별 엔드 포인트에 대해 약간 더 많은 작업을 수행해야합니다.
따라서 "이전 버전을 지원하기 위해 REST 서비스 코드를 디자인하는 가장 좋은 방법은 무엇입니까?"라는 두 번째 질문이 있습니다.