JSON을 API 요청 매개 변수의 형식으로 사용 (내 웹 앱용 API 설계)

Question

웹 애플리케이션 용 API를 설계하고 있으며 내용은 매우 복잡합니다. 예를 들어 태그, 여러 개별 콘텐츠 영역 등 여러 개의 하위 오브젝트가 포함 된 위키 페이지를 만들 수 있습니다.

나는 tag_N 또는 tag []와 같은 매개 변수를 명명하는 복잡하고 번잡 한 방법을 다루고 싶지 않습니다.

우리의 객체가 JSON으로 완벽하게 표현 될 수 있다는 것도 나에게 발생했습니다. 사실 그것은 우리의 응답 형식입니다. GET을 수행하면 개체가 JSON 형식으로 수신됩니다.

개체의 POST 및 PUT 본문도 JSON에 지정하도록 요구하는 것이 합리적입니까? 이 같은 예를 들어 뭔가 :

{ 
'name' : 'My Page', 
'body' : 'Some page body', 
'tags' : ['tag1', 'tag2', 'tag3'] 
} 

name=My%20Page&body=Some%20page%20body&tag[]=tag1&tag[]=tag2&tag[]=tag3 

이 반대로 꽤 간단한 예이다. 많은 경우 우리는 복잡한 객체를 하위 객체의 배열과 함께 가지고 있습니다. 하위 객체 자체에는 하위 객체도 포함됩니다. JSON으로 설명하는 것은 매우 간단하지만 쿼리 문자열 스타일 매개 변수에서는 매우 어려워집니다.

그래서 주된 질문은 POST 몸체가 JSON 문자열이어야하는 경우 불합리한가? HTTP API의 표준 외부에서 너무 멀리 떨어져 있습니까? API 소비자의 저작자로서 이와 같은 요구 사항을 가진 API에 의해 연기 될 수 있습니까?

Answer 1

이것은 JAX-RS/REST API에서 매우 일반적입니다.

Answer 2

그건 무리가 아닙니다. 여기서 (a) 데이터 형식, (b) 인코딩 및 (c) REST 디자인 철학 등 몇 가지를 혼합 할 수 있습니다.

일반적으로, 나는 다음과 같은 제안 :

• 데이터 형식 (일관성이 있어야를 예를 들어, JSON 자원의 모든 CRUD 방법에 대한 기준으로, 당신은 XML을 지원하는 경우가 좋은 것뿐만 아니라 때문에 그 편재성의 - 많은 프레임 워크가 자동으로 당신을 위해)

• 인코딩은 데이터 전송 형식과 분리해야합니다; 예를 들어 URL에는 본문 인코딩과 약간 다른 인코딩이 있습니다. 이를 데이터 형식과 혼동하지 마십시오.

• 리소스를 가능한 한 REST-ful로 모델링 할 것을 제안하십시오. 생성을 위해 POST를 사용하고, 읽기 용으로 GET, 업데이트 용 PUT, 삭제를위한 DELETE를 대부분의 경우에 사용합니다.