Rest API에 대해(3)

앞의 두 글을 통하여 Rest API에 대해 소개했고 설계에 있어 직관적으로 설계해야 함을 설명했다.

이번 글은 Rest API를 예측가능하게 설계하는 것에 대하여 다루어 볼려고 한다.

예측 가능하게 설계하려면 일관성, 적응성 넓은 커버리지를 갖도록 설계해야 한다. 아래 각각에 대해여 살펴보자.

일관성

이 특성은 API를 설계함에 있어서 제일 중요한 특성이라고 생각 한다. 일관성이 있게 설계하면 이글의 목표 예측 가능한 API를 설계하는 목표에 도달할 수 있게 된다.

예를 들어 날짜 표시를 어떤 곳에는 createDate라고 쓰고 다른 곳에는 dateUpdate라고 쓰면 일관성 원칙도 지켜지지 않고 가독성도 떨어진다. 일관성을 맞춰야하는 Level를 아래와 같이 정의할 수 있다.

• Level 1 : 한 API내에서 일관성 지키기
• Level 2 : 팀, 회사 혹은 단체 내에서 일관성 지키기
• Level 3 : 같은 도메인에서의 일관성 지키기
• Level 4 : Rest API 설계함에 있어 암묵적 일관성 지키기 (예를 들면 여러 제품을 표시하는건 복수로 사용)

적응성

수요에 의하여 여러가지 포맷을 지원해야 할 경우가 생긴다. 이럴때 적응적으로 여러 format에 대한 지원을 해줘야 한다. 예를 들어 Requst 요청 시 Accept 속성을 이용하여 Response의 포맷을 지정할 수 있게 만드는 경우 이다. 잘못된 포맷으로 요청했을 경우에 대해서도 상응한 에러 메시지를 사용자한테 보내 줘야 한다.

적응성을 높이는 방법에는 사용자한테 paging 및 sorting 방식을 제공하는 방법이 있다.

Paging를 설계시 사용자로부터 pageSize와 현재 page를 받아 해당 페이지 아이템만 넘겨주는 방법이다.

**GET /accounts/1232345/transactions?pageSize=10&page=2** 

Sorting 방식은 아래와 같이 제공할 수 있다.

GET /accounts/1234567/transactions?sort=-amount,+date

넓은 커버리지

책을 읽으면 목차가 존재한다. 목차를 이용하여 읽고 싶은 내용을 읽을 수 있다. Rest API를 설계함에 있어 이런 목차같은 가이드을 제공할 수 있다. 바로 Metadata를 통하여 제공 할 수 있다.

예를 들어 현재 API에서 Page 기능을 제공하고 있고 현재 조회한 page와 tatal page를 제공함으로써 사용자로하여금 다른 페이지 내용을 쉽게 접근하게 할 수 있다. 또한 사용자가 할 수 있는 액션을 정의 함으로하여 사용자가 머므르고 있는 페이지에서 할 수 있는 action를 정의 할 수도 있다.

{
    "pagination":{
        "page": 1,
        "totalPages":9
    },
    "items":[
        {
            "id":"00012",
            "date":"2021-03-01",
            "actions":["cancel"]
        }
    ]
}

여기서 좀 더 친절하게 data에 hypermedia를 넣어서 다음 액션에 대한 네비게이트를 할 수 있다.

{
    "pagination":{
        "page": 1,
        "totalPages":9,
        "next":"/accounts/12334/transactions?page=2",
        "last":"/accounts/12334/transactions?page=9"
    },
    "items":[
        {
            "id":"00012",
            "date":"2021-03-01",
            "actions":["cancel"]
        }
    ]
}