Rest API에 대해(2)

이번 글에서는 직관적인 Rest API를 설계함에 있어 지켜야 할 원칙에 대해 적어 보려고 한다. 이 내용은 The Design of Web APIs 를 참고 했으며 내가 생각하기에 합당한것들만 정리하였다.

직관적인 표현방식을 사용

데이터를 정의함에 있어서 직접적이고 명확한 이름과 명확한 type를 정하는 것이 바람직하다.(클린 코드에서도 강조하는 부분이다.)

애매모호한 data type으로 API 데이터를 표현하지 말아라. 예를 들어 알람 시계에서 알람 시간 표현을 현재시간부터 몇초 남았는지를 표현 하는것이 아니라 몇시 몇분에 알람이 울릴 것인지를 표현하라. 사실 우리가 API 데이터를 설계함에 있어 자주 범하는 실수이다.

데이터를 표현함에 있어 이름은 직관적이면 좋다. 예를 들어 bkAccOverProtFtActBln 이 이름만 듣고 무엇인지 감이 오는가 ? 이것을 좀 더 직관적으로 바꾸면 bankAccountOverdraftProtectionFeatureActiveBln 이다. 이것을 좀 더 간략하게 사용할 수 있다. 예를 들어 이 API가 bankAccount에 관련된 API이면 overdraftProtectionFeatureActiveBln이라고 쓸 수 있다. 또한 이 속성의 타입이 boolean인것을 감안하면 overdraftProtectionFeatureActive 으로 사용 가능하다.

마지막으로 중복된 데이터라도 사용자한테 유용한 데이터면 제공하는 것이 좋다.

예를 들어 은행 계좌에 정보를 보여주는 API를 정의 할때 현재 잔액과 대출가능 금액을 보여 줄 수 있지만 추가로 인출 가능한 금액을 보여주면 좀 더 직관적이다.

직과적인 Interaction 사용

입력에 대한 직관성

Request의 입력이 직관적이여야 한다. 입력 정의에 있어서 좀 더 명확하게 사용자한테 좀 더 친절하게 다가갈수 있는 방식을 써야 한다.

처음의 json 포맷보다 개량한 3번째 방법이 더욱 직관적이다.(from The Design of Web APIs Chapter5)

Feadback에 대한 보충설명

될수록이면 이미정의된 Error code에 대하여 보충 설명을 같이 response 해주면 좋다. 예를 들어

200 OK에대하여서는 좀 더 자세히 나열하면 좋다.

202 Accepted
{
"id": "000001",
"source":"00123455",
....
}

에러에 대해서도 좀 더 자세한 정보를 보내주면 좋다.

404 Bad Request
{
        "message": "Invalid reqest",
        "errors":[
            {
                "source": "destination",
                "type": "MISSING_MANDATORY",
                "message": "Destination is mandatory"
            }
        ]
}

직관적인 flow 설계

하나의 요구사항을 만족시키기 위해서는 하나 혹은 하나 이상의 API가 조합하여 만들어 가야 한다.

예를들어 은행의 이체를 옐들 들어 설명하면

• 현재 사용자의 신분이 정확해야 한다.(권한 관련[로그인])
• 보내려는 금액이 통장안에 있어야 한다(금액조회)
• 목표 통장이 유효해야 한다.(목표 통장이 이미 있음을 확인 필요함)
• 위의 사항이 모두 유효하다면 송금을 진행 시킨다.

명확한 flow와 각 단계에서 필요한 데이터와 권한들을 모두 나열하게끔 설계 되여야 한다.