Chapter 13 : JSend

이 글은 Github 문서 기준으로 작성됩니다.
https://github.com/omniti-labs/jsend

 

 

• JSend

JSend는 Application level의 통신을 위한 단순하고 간단한 JSON 기반 형식의 사양입니다.

 

1. What?

JSend는 웹 서버의 JSON 응답 형식을 지정하는 방법에 대한 몇 가지 규칙을 규정 한 사양입니다. JSend는 protocol-level 또는 transport-level과 달리 Application-level message에 중점을 두어 REST 스타일 Application 및 API에서 사용하기에 이상적입니다.

 

2. Why?

JSON 데이터를 제공하는 많은 웹 서비스가 있으며, 각각 고유 한 형식의 응답 형식이 있습니다. 그런데, 개발자들은 과연 Javascript만을 쓸까요? 프론트엔드 세계는 서버와의 통신에 있어 계속 새로운 기술이 나오고 있습니다. 데이터를 구성하는 데는 공통적인 패턴은 많이 있지만, naming 또는 types of responses와 같은 항목에는 일관성(약속)이 없습니다.

또한 모든 사람이 서로 상호 작용하는 일반적인 접근 방식을 기대할 수 있기 때문에 백엔드 개발자와 프론트 엔드 디자이너 간의 약속(통일성)을 개선하는데 도움이됩니다.

 

3. 잠깐, 위의 내용 역할을 해내는 다른 유사 기능은 없나요?

안타깝게도, 없습니다. JSON 데이터, 특히 Douglas Crockford의 JSONRequest 을 다루기위한 몇 가지 기능은 있지만 일반적인 Application 수준 메시징의 문제를 해결할 수 있는 것은 없습니다.

 

4. (Why) Should I care?

library 또는 framework 개발자 인 경우 사용자에게 이미 약속된 형식을 제공하므로 코드를 사용하고 코드와 상호 작용하는 방법을 이미 알고 있을겁니다.

웹/앱 개발자인 경우, Application에서 JSON 데이터를 구성하는 법에 대해 생각할 필요가 없으며, 기존 참조 구현을 통해 빠르게 시작하고 실행할 수 있습니다.

 

 

• So, How does it work?

기본 JSend-호환 response는 아래와 같이 간단히 표현해낼 수 있습니다.

{
    status : "success",
    data : {
        "post" : { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
     }
}

 

JSON API를 설정할 때 모든 종류의 호출 및 response이 있습니다. JSend는 response을 몇 가지 기본 유형으로 분리하고 각 유형에 대해 필수(required keys) 및 선택적 키(optional keys)를 정의합니다.

Type	Description	Required Keys	Optional Keys
Success	request 기반 작업에 대해 모두 잘 진행되었으며, response data가 returned.	status, data
fail	request 때 제출된 데이터에 문제가 있거나, API 호출의 일부 조건에 대해 맞지 않음.	status, data
error	request을 처리하는 중에 오류가 발생했습니다 (예 : exception 발생)	status, message	code, data

 

 

• Example response types

1. Success

API 호출이 성공하면 JSend 객체는 data key를 사용하여 아래와 같은 결과를 보여줍니다.

## GET /posts.json:

{
    status : "success",
    data : {
        "posts" : [
            { "id" : 1, "title" : "A blog post", "body" : "Some useful content" },
            { "id" : 2, "title" : "Another blog post", "body" : "More content" },
        ]
     }
}

## GET /posts/2.json:

{
    status : "success",
    data : { "post" : { "id" : 2, "title" : "Another blog post", "body" : "More content" }}
}

## DELETE /posts/2.json:

{
    status : "success",
    data : null
}

Required keys:

• status  "success"를 반환합니다.
• data  API 호출에서 반환한 모든 데이터를 감싸는(wrapper) 역할을 합니다. 마지막 예(DELETE Method)에서와 같이, 호출에서 데이터가 반환되지 않으면 데이터를 null로 설정해야합니다.

2. Fail

When an API call is rejected due to invalid data or call conditions, the JSend object's data key contains an object explaining what went wrong, typically a hash of validation errors. For example:

 

유효하지 않은(not validates) 데이터 또는 호출 조건으로 인해 API 호출이 거부되면 JSend 오브젝트의 data key에는 문제점을 설명하는 객체(일반적으로 유효성 검증 오류의 hash)가 포함됩니다.

## POST /posts.json (with data body: "Trying to creating a blog post"):

{
    "status" : "fail",
    "data" : { "title" : "A title is required" }
}

Required keys:

• status  "fail"을 반환합니다.
• data  request이 실패한 이유를 제공합니다. 실패 이유가 POST values에 해당하는 경우, response 객체의 Key는 해당 POST 값에 해당해야합니다.

3. Error

서버 오류로 인해 API 호출이 실패한 경우 아래와 같이 표현됩니다.

## GET /posts.json:

{
    "status" : "error",
    "message" : "Unable to communicate with database"
}

 

Required keys:

• status  "error"을 반환합니다.
• message  무엇이 잘못되었는지에 대한 message가 있고, 최종 사용자가 읽을 수있는 (또는 최소한 로그에 적합한) 메시지입니다.

Optional keys:

• code  오류에 해당하는 status code(404, 500 등등)
• data  오류에 대한 정보(오류가 발생된 원인 부분, stack traces 등)

 

 

• Whither HTTP?

HTTP는 이미 응답 상태(response status)에 대한 전달을 제공합니다. 그런데 message body에서 response status를 나타내는 개념은 어떻게 HTTP context에 적합하다는 걸까요?

• 공식 HTTP 사양에는 41개 이상의 상태 코드가 있으며 각 코드를 사용하는 방법에 대한 많은 해석이 있습니다. 반면에 JSend는 동적 웹 UI의 맥락에서 JSON 트래픽 처리와 관련하여 보다 제한적인 상태 코드 설정을 정의합니다.
• 사양은 가능한 작고 제한적이며, 일반적으로 적용 가능한 것으로 간주됩니다. 따라서 다소 독립적이어야합니다. JSON 서비스를 구현하는 일반적인 패턴은 JSON 블록을 사용자 지정 콜백에 전달하는 JavaScript 파일을 load하는 것입니다. 많은 JavaScript 프레임 워크에서 JSON-over-XHR 처리는 유사한 패턴을 따릅니다. 따라서 최종 사용자(개발자)는 HTTP 응답 자체에 접근할 기회가 없습니다.

 

 

• License

BSD License 로서, 저작권 및 라이선스 명시 이외엔 아무 제약이 없이 사용 가능한 자유로운 라이선스

 부록  오픈소스 License 특징