사물 인터넷 기기 실습 - API 설계 실습

사물 인터넷 기기 실습 - API 설계 실습

웹/앱 API의 설계

1. 웹/앱 API의 기술

웹/앱 API의 설계

사물인터넷의 사물들은 개방형 API를 가지고 있고, 이 인터페이스를 통하여 메시지를 주고받음으로써 대화하는 것입니다.

웹 API의 REST 기술을 그대로 사물 간의 통신에 사용할 수 있는데, 사물의 특징은 그 사물이 표출하는 API에 의하여 규정될 수 있습니다.

웹 API 기술 중에서 먼저 URL에 대하여 알아보도록 하겠습니다. 개발자 관점에서 API를 파악할 때, URL이 간단하면 이해하기 쉽습니다. 자원에 대하여 화면의 표와 같이 나타낼 수 있는데, 2가지 기본 URL을 사용하며, 가급적 동사를 사용하지 않고, HTTP 메소드를 동사로 사용하는 방법이 사용됩니다.

다음은 자원 이름의 좋은 예시입니다.

화면과 같이 단수형의 명사나 복수형의 명사를 자원의 이름으로 사용하는 예는 유명한 API에서 많이 볼 수 있습니다.

이렇게 자원의 이름은 추상명사보다 일반명사를 사용하는 것이 구체적이어서 개발자가 이해하기 좋습니다. 그리고 되도록이면 소문자를 사용하는 것이 좋은데, 그 이유는 URL은 대소문자를 구별하는데, 대문자를 섞어서 사용할 경우 실수하기 쉽기 때문에 실수를 사전에 방지하기 위해서 소문자 사용이 권장됩니다.

URI 뒤에 붙는 쿼리의 용도를 알아보도록 하겠습니다. 흔히 GET 요청을 보낼 때, 쿼리 스트링을 이용하여 추가로 요청 사항을 전달합니다. 예를 들어,URL에는 다음과 같은 기호를 볼 수 있는데, 이때 물음표는 자원의 상태나 속성을 표현하는 데 사용됩니다. 가령, 특정 리소스에 대한 질의를 보낼 때, 그 집합이 너무 거대할 수 있으므로 필요한 정도의 정보만을 요구하기 위해서 구분 값을 쿼리 스트링에 포함할 수 있습니다. 대표적인 쿼리 스트링으로는 ?, =, & 기호 등이 있습니다.

쿼리가 어떻게 사용되고있는지 구체적인 예를 살펴보겠습니다.

페이스북은 다음과 같이 URL을 표시하는데, 물음표 뒤에 적혀있는 부분을 살펴보면, 아이디, 이름, 이미지 등을 설정하고 있습니다. 이것은 이름이 joe, smith인 사람의 정보를 가져오되, 아이디, 이름, 이미지 등 필드를 제한해서 가져오도록 하는 것입니다.

Linked In의 예를 살펴보면, 콜론과 괄호를 사용하여 내용을 제한하고 있는 것을 확인할 수 있습니다. 다시 말해 people 리소스를 요청하되 필요한 필드에 대해서만 괄호를 묶어 지정하고 있는 것입니다.

구글 또한 비슷한 쿼리의 사용을 보여줍니다. 물음표로 필드를 설정하여 구체적인 검색결과가 나타날 수 있도록 검색결과를 제한하고 있습니다.

API들은 응답 메시지에 상태 코드로서 오류를 알려줍니다.

예를 들어, 페이스북, Twilio, SimpleGeo API의 오류 메시지를 살펴 볼 수 있습니다. 페이스북은 상태 코드는 정상이나 메시지에 오류 정보를 실었고, 나머지 API는 상태 코드 401로 그 자체가 오류를 뜻하는 것입니다.

상태 코드의 종류에는 3가지가 있습니다. 200은 정상 코드, 400은 클라이언트 측 오류 코드, 500은 서버 측 오류 코드를 나타냅니다.

이러한 오류코드는 개발자가 API의 행동양식을 이해하기 좋아서 생산성 향상에 도움이 됩니다.

상태 코드에 대해 좀더 구체적으로 알아보도록 하겠습니다.

먼저, 201 코드는 리소스 생성 성공을 의미하며, CRUD 요청 중 생성(Create) 요청에 대한 응답으로 사용할 수 있습니다. 응답 헤더의 Location 필드에 생성된 리소스에 접근할 수 있는 URI를 포함할 수 있다면 브라우저에서 그 값을 참조하여 적절히 대응할 수 있을 것입니다.

202 코드는 처리 시간이 오래 걸리는 비동기 요청에 대한 응답으로 사용됩니다. 그렇기 때문에, 요청에 대한 응답이 결과를 포함하지 않을 수 있습니다. 이 응답은 최소한 응답 헤더, 혹은 응답 데이터에 해당하는 처리를 모니터링 할 수 있는 리소스 페이지를 안내하거나 처리되기까지 걸리는 예상 경과 시간 등을 안내하는 것이 더 좋은 설계라고 할 수 있습니다.

다음으로, 301 코드는 리소스가 이동되었을 경우에 응답하는 코드로, 이동된 URI를 응답 Location 헤더에 명시해야 합니다. 이 응답을 받은 클라이언트는 새 URI로 이동하거나 URI를 갱신 혹은 캐싱하는 등의 대응이 필요합니다.

400 코드는 일반적인 요청 실패에 사용합니다. 대체로 서버가 이해할 수 없는 형식의 요청이 왔을 때 응답하기 위해 사용되는데, 400 코드를 남발하기 보다는 구체적인 코드를 부여하는 것이 해당 에러에 대한 의미를 잘 설명할 수 있기 때문에 권장됩니다.

401코드는 리소스 접근 권한을 가지고 있지 않다는 의미로 사용됩니다. 리소스 획득을 위하여 요청자는 인증에 필요한 헤더나 데이터를 첨부해야 합니다.

403은 감춰진 리소스에 접근하려고 할 때의 응답 코드입니다. 401과 달리 인증 여부와 관계없이 리소스를 보여주지 않으며, 클라이언트 측에서 공개하고 싶지 않은 정보를 포함하는 리소스임을 나타내기 위해 사용됩니다.

404는 가장 흔한 상태 코드로 해당 URI와 매치되는 리소스가 없음을 나타냅니다.

다음으로, 405 코드는 지원하지 않는 요청, 예를 들어, POST 요청을 받는 컨트롤러 리소스에 대해 GET 요청을 보내는 등, 불가능한 요청을 하였을 때 사용합니다. 가능하다면  응답 메시지에 Allow 헤더를 추가하고 그곳에 지원하는 메소드를 명시하여 클라이언트 측에서 정확한 요청을 보낼 수 있도록 유도하는 것이 권장됩니다. 406 코드는 해당 미디어 타입에 대해 지원하지 않을 때 사용하는데, 요청 Accept 헤더에 명기된 타입에

대해서 지원이 불가능할 경우에 돌려주면 되는 코드입니다.

409 코드는 요청의 형식에는 문제가 없지만 리소스 상태에 의하여 해당 요청 자체를 수행할 수 없는 경우의 응답코드입니다. 예를 들어, 이미 삭제된 리소스를 또 삭제하거나, 비어있는

리스트에서 무언가를 요청하는 등의 모순된 상황에 사용됩니다. 응답으로는 문제를 어떻게 해결할 수 있을지에 대한 힌트가 포함되도록 하는 것이 좋습니다. 500 코드는 일반적인 서버 에러에 대한 응답을 할 때 사용됩니다.

그리고 503 코드는 서버에 과부하가 걸려 있거나 유지보수를 위하여 잠시 접근이 거부될 때 필요한 응답 코드입니다. 다소 복잡하다고도 느껴질 수 있는 상태 코드를 전부 암기하고 있을 필요는 없습니다. 그러나 브라우저에서, 혹은 서버 단에서 특정 상태 코드에 대한 내부 구현을 개선하거나, 최적화를 통해 더 쾌적한 환경을 제공할 가능성이 있으므로 되도록 의미에 걸맞은 상태 코드의 사용을 생활화하는 것이 중요합니다.

상태 코드의 관용적인 용례 살펴보기 위해 다음 사이트를 참고합니다.

http://www.restapitutorial.com/httpstatuscodes.html

2. API의 메시지의 예

API의 메시지의 예를 살펴보도록 하겠습니다. 이것은 하나의 자원을 생성하는 API 메시지의 예입니다. JSON 포맷으로 응답메시지의 본문이 온 것입니다. “tom”이라는 이름의 자원이 생성된 것을 확인할 수 있습니다. 자원의 속성을 갱신하는 메시지를 살펴보겠습니다. 이와 같은 메시지를 보내면, 자원의 이름이 “john”으로 변경되었음을 알 수 있습니다. 자원을 삭제하는 메시지는 다음과 같습니다. 정상적으로 처리되면 다음과 같은 메시지가 전송됩니다.

3. API  설계 과정

API를 설계하는 과정을 알아보도록 하겠습니다. 4가지의 설계 과정으로 세분화 되는데, 먼저, 자원에 대한 정보를 나열한 후, 상태 다이어그램을 작성합니다. 그리고 미디어 타입을 설계하며, API를 구현하고, URL을 등록하는 것으로 완료됩니다.

예를 들어, 온도 센서용 API를 설계한다고 가정해 보겠습니다. 정보의 나열 단계에서는 우선, 센서의 리스트가 필요합니다. 가장 먼저 생각할 수 있는 온도 센서는 온도계입니다. 온도계에는 온도 데이터, 마지막 온도, 현재의 온도 상태 등을 구성할 수 있습니다. 온도 데이터는 생성시간과 측정 단위 등의 내용을 생각할 수 있습니다.

온도 센서용 API를 만들 때 필요한 또 다른 센서로는 무엇이 있을까요? 여기에서 스위치를 설정해 보겠습니다. 스위치는 온도 센서를 껐다 켜는 용도로 ON/OFF 두 가지 상태가 있습니다. 정보의 나열을 기반으로 상태 다이어그램을 작성합니다. 먼저, 온도 센서의 리스트를

다루고, 개별 온도 센서는 스위치와 온도 정보를 얻을 수 있습니다. 이때 ON/OFF를 몇 번 요청하든 결과는 독립적이므로 멱등이라고 할 수 있습니다. 멱등은 동일 요청이 서버에 어떤 잘못된 결과를 야기하지 않고 두 번 이상 이루어질 수 있음을 뜻하며, API 설계에 있어서 중요한 고려 사항입니다. 온도 정보는 온도의 리스트를 얻고, 마지막 온도 정보를 얻을 수 있습니다.

온도 정보에는 온도의 측정 단위 정보, 온도의 측정 시간 정보 등이 포함됩니다.

상태 다이어그램을 작성하면, 다음으로 미디어 타입의 설계를 합니다. 다음은 앞에서 작성한 내용을 JSON 포맷으로 설계한 예입니다.

화면에서는 모두 한 개의 센서와 한 개의 온도 데이터를 표현하였지만 여러 개의 센서와 온도 데이터를 표현할 수 있습니다. 마지막 단계는 API를 구현하는 단계입니다. 이 단계에서는 요청/응답 메시지에 대한 간단한 설명을 기술하고 API 리스트 명세를 작성하면 API 설계를 마무리할 수 있습니다.