웹 API 설계: 놓치기 쉬운 핵심 - 서문

 

 

서문

 

 

웹 API 설계의 최첨단은 웹 API가 비즈니스와 기술에서 점점 더 중요해짐에 따라 지속적으로 발전하고 있습니다.
API 관리 분야의 리더인 Apigee는 수백 명의 고객과 협력하여 다수의 API를 개발하고 관리해왔습니다. 우리의 경험과 고객, 그리고 전체 산업의 경험을 되돌아보며, 어떤 API 설계 혁신이 실제로 혜택을 가져오고 주목할 만한 트렌드로 자리 잡고 있는지에 대한 통찰을 얻을 수 있었습니다.

이 책은 지난 몇 년 동안 등장한 API 설계의 중요한 트렌드를 담아내기 위한 시도입니다. 이 책은 명확하고 간단하게 설명하려고 노력했지만, API 설계에 대한 초급자용 가이드로 작성된 것은 아닙니다. 초보자를 위한 자료를 찾고 계신다면, Apigee에서 이전에 출간한 책들이나 이 주제에 관한 많은 다른 텍스트들을 참고하는 것이 좋습니다.

우리의 이전 책에서는 개와 그 주인을 추적하는 간단한 애플리케이션 예제를 사용했습니다. 이 책에서는 그 예제가 API에 대한 최근 사고방식을 어떻게 반영해 발전할 수 있는지 보여주고 있습니다. 다음은 이전 책에서 다뤘던 두 가지 예시 자원(resource)입니다:

 

https://dogtracker.com/dogs/12345678:
{
    "id": "12345678",
    "kind": "Dog",
    "name": "Lassie",
    "furColor": "brown",
    "owner": "98765432",
};

 

그리고

 

https://dogtracker.com/persons/98765432:
{
    "id": "98765432",
    "kind": "Person",
    "name": "Joe Carraclough",
    "hairColor": "brown"
}

 

API는 클라이언트가 이러한 자원에 대해 여러 가지 특정 작업을 수행할 수 있게 해줍니다. 예를 들어, 개를 주면 주인에 대한 정보를 가져오고, 사람을 주면 그 사람에게 속한 모든 개를 가져올 수 있습니다. 이러한 기능을 API에서 노출하는 일반적인 방법은 클라이언트가 자원에 있는 정보를 사용해 URL을 구성할 수 있도록 URI 템플릿을 정의하는 것입니다. (URI 템플릿이 익숙하지 않다면, URI 템플릿은 값으로 대체되어 실제 사용 가능한 URL을 만들 수 있는 변수가 포함된 URL과 비슷한 개념입니다.) 위의 예시에서 우리는 다음과 같은 URI 템플릿을 설명할 수 있을 것입니다.

 

https://dogtracker.com/persons/{personID}
https://dogtracker.com/persons/{personID}/dogs
https://dogtracker.com/dogs/{dogID}

 

이 템플릿들은 위에 언급된 개에 대한 데이터를 가지고 있는 클라이언트가 개 주인에 접근하기 위한 다음 URL을 구성할 수 있게 해줍니다.

 

https://dogtracker.com/persons/98765432

 

마찬가지로, 클라이언트는 모든 주인의 개에 접근하기 위해 이 URL을 구성할 수 있습니다.

 

https://dogtracker.com/persons/98765432/dogs

 

HTTP 메서드인 GET, POST, PUT 또는 PATCH, 그리고 DELETE는 이 템플릿들과 함께 사용되어 개와 그 주인에 대한 자원 설명을 읽고, 생성하고, 업데이트하고, 삭제할 수 있습니다.
이 API 스타일은 여러 가지 이유로 인기를 끌고 있습니다. 직관적이고 간단하며, 이 패턴을 배우는 것은 프로그래밍 언어의 API를 배우는 것과 비슷합니다.
이와 같은 API들은 흔히 RESTful API라고 불리지만, REST를 정의하는 모든 특징을 나타내지는 않습니다(REST에 대해서는 나중에 더 다룰 예정입니다).

 

 

 

 

 

[출처]

APIGEE-WEB-API-DESIGN-THE-MISSING-LINK