Jwhy

Jwhy

끊임없이 고민하는 개발자

[Chapter15] 읽기 전용 웹 서비스의 설계

웹을 지탱하는 기술을 공부하며 정리한 글입니다.
틀린 부분은 지적해주시면 감사드리겠습니다 😀

리소스 설계

리소스 설계란, 클라이언트와 서버 간 인터페이스의 설계를 의미한다. 즉, 어떻게 리소스를 분할하고, URI로 이름을 붙이고, 상호 링크를 가지게 하는 등의 웹 서비스와 웹 API의 외부 설계를 의미한다.

설계란, 시스템을 어떤 구조로 어떻게 개발할 것인지를 검토하고, 그림이나 문서로 남기는 작업을 의미

리소스 지향 아키텍처의 어프로치

리소스 설계에는 아직 표준적인 설계 방법이 존재하지는 않지만, 유일하게 존재하는 지침은 ‘RESTful 웹 서비스’라는 책의 리소스 지향 아키텍처(Resource Oriented Architecture)의 설계 어프로치이다.

  1. 웹 서비스에서 제공할 데이터 특정
  2. 데이터를 리소스로 나눔
  3. 각 리소스에 URI로 이름 부여
  4. 클라이언트에 제공할 리소스의 표현 설계
  5. 링크와 폼을 이용해 리소스와 리소스 연결
  6. 이벤트의 표준적인 코스 검토
  7. 에러 검토

책과 동일하게 우편번호를 검색하되, 일본의 우편 번호가 아닌 한국의 우편번호를 기반으로 생각해보자. 우선, 한국의 우편번호는 어떤 정보를 제공하는지 살펴보자.

  • 우편번호 정보는, 우편번호, 주소로 구성된다.
  • 주소는 시도, 시군구, 도로명으로 구성된다.
  • 주소 및 주소 읽기로 우편 번호 정보를 전문 검색(full text searching)할 수 있다.
  • 데이터는 모두 읽기 전용이다.

웹 서비스에서 제공할 데이터 특정

이 서비스에서 제공할 데이터는, 우체국에서 공개하고 있는 우편 번호의 txt 데이터를 기반으로 한다. 해당 파일에서 우리가 주의깊게 봐야하는 데이터는 다음과 같다.

  • 5자리의 우편변호(구역 번호)
  • 도로명 주소
  • 지번 주소

데이터를 리소스로 나눔

리소스란, 웹 상의 존재하는 이름이 부여된 정보를 의미한다. 그렇다면 이 서비스에서는 우편번호를 제공하기 때문에, 우리가 갖고 있는 데이터는 우편번호를 기반으로 리소스를 나누면 된다.

우편번호 13561은 ‘경기도 성남시 분당구 정자일로 95 네이버 1784’라는 정보를 갖고 있다. 여기서 ‘경기도’는 시도의 명칭이고, ‘성남시 분당구’는 시군구의 명칭, ‘정자일로 95’는 도로명의 명칭이다.

각 리소스에 URI로 이름 부여

우편번호는 유일하게 식별이 가능하기 때문에, URI에는 우편번호를 사용하는 것이 좋다. 검색결과 리소스의 경우, 검색 키워드의 입력을 필요로 한다.

https://www.epost.go.kr/search?q=정자일로95

실제 우체국에서 사용하는 시스템은 아니지만, 위와 같은 형태로 쿼리 파라미터를 사용할 수 있다. 만약, 지역 리소스를 구분한다면 다음과 같은 계층 구조를 사용할 수도 있다.

https://www.epost.go.kr/경기도/성남시/분당구

클라이언트에 제공할 리소스의 표현 설계

단순한 우편번호 검색 서비스를 사용하기 때문에, JSON 포맷을 이용해보도록 하자.

{
  "zipcode": "13561",
  "adderss": {
	  "city": "경기도",
	  "state": "성남시 분당구",
	  "streetAddr": "정자일로",
	  "address2": "네이버1784"
  }
}

이제, 검색 결과 리소스를 JSON을 이용한 형태로 보여주려면, 다음과 같은 URI를 갖게 된다.

https://www.epost.go.kr/search?q=네이버1784&type=json

링크와 폼을 이용해 리소스와 리소스 연결

웹 상에 존재하는 리소스에는 링크가 불가결하다. 링크가 없다면 그 가치가 크게 감소한다. 여러 개의 검색 결과를 JSON으로 표현하면 다음과 같다.

"meta": {
	"total": 112,
	"rowPerPage": 10,
	"totalPage": 11
}
"result": [
	{
	  "zipcode": "13561",
	  "adderss": {
		  "city": "경기도",
		  "state": "성남시 분당구",
		  "streetAddr": "정자일로",
		  "address2": "네이버1784"
	  }
	},
		{
	  "zipcode": "13561",
	  "adderss": {
		  "city": "경기도",
		  "state": "성남시 분당구",
		  "streetAddr": "불정로",
		  "address2": "네이버그린팩토리"
	  }
	},
	...
]

클라이언트는 이를 통해 각 우편번호를 가지고 URI를 연결하고, HTML 형식으로 그려낼 수 있다.

이벤트의 표준적인 코스 검토

우리가 예상하는 이용자의 표준 코스는 다음과 같다.

  1. 폼에 우편번호 혹은 주소를 입력한다.
  2. 검색 결과 리소스를 취득한다.
  3. 찾고자하는 우편번호 리소스를 취득한다.

에러 검토

가장 흔하게 일어날 수 있는 에러는 바로, 잘못된 URI를 지정한 경우이다.

https://www.epost.go.kr/-12345

위와 같이 존재하지 않는 URI를 지정한 경우, 404 Not Found를 반환하도록 하고, 필수 쿼리 파라미터 혹은 잘못된 HTTP 메소드를 사용한 경우에 대해서도 모두 검토를 해야 한다.

댓글남기기

참고