REST API 헤더 수락 json/pdf

Question

현재 REST API 구현이 잘못되었다고 생각하는 API를 사용하고 있습니다.

우리는 다음과 같은 엔드 포인트

이

1. GET의 V1/{organizationId}/송장
2. GET의 V1/{organizationId}/송장/{GUID}

첫 번째 GET , 모든 송장을 얻을 수 있지만 Accept: Application/json 헤더가없는 두 번째 끝점을 얻으면 첫 번째 끝점에서 응답을받습니다. API를 제공

이 회사는 두 번째 엔드 포인트가 게다가

GET v1/{organizationId}/invoices/{guid}/pdf 

것 PDF로 보일 수있을 것입니다 모두 JSON과 PDF 출력을 제공 할 수 있기 때문에 이것에 대한 이유가있는 경우, 말한다 기형의 guid을 보내면 빈 페이지 또는 오류 메시지 대신 예를 들어 HTML 404 오류 페이지 전체가 표시됩니다.

1. 은 2 엔드 포인트가 제대로 처리를 요약하면?
2. PDF를 JSON/XML과 같은 출력으로 만들 수 있습니까?
3. 대신 새로운 엔드 포인트가되어야합니까?
4. 형식이 잘못된 요청 인 경우에도 HTML이 오류 응답으로 허용됩니까?

Answer 1

어떤 사람들은 "오른쪽"와 "잘못"REST 기반의 질문을 분류하고 싶지 않지만, 어쨌든 진행됩니다

1. 아니, 두 번째 자원은 항상 표현을 반환해야 인보이스가 아닌 인보이스 모음입니다.

2. 예, 잠재적으로 동일한 "물건"을 여러 번 표시 할 가능성이 있습니다. 인보이스는 json과 pdf를 모두 반환 할 수 있으며 '수락'헤더를 기반으로 올바른 송장을 선택할 수 있습니다.

3. 아니요,이 "사물"이 "끝점"이 아니기 때문에 새로운 "끝점"이 아니어야합니다. 인보이스는 리소스이고, json 문서는 리소스의 "표현"입니다.

4. 예, 오류 응답에는 서버에서 전송하기 쉬운 표현이있는 본문이 포함될 수 있습니다. 물론 서버는 클라이언트의 "Accept"헤더를 사용하여 자신의 방향을 지정해야하지만 반드시 그렇게 할 필요는 없습니다.

몇 가지 발언

:이 자원 해야하기 때문에 그것은 잘못된 GUID와 GET 송장에 가능하지 않아야 컬렉션 리소스에서를 연결. 클라이언트가 링크를 따라갈 때 (틀림없이), 잘못된 guid가있는 링크를 따라갈 방법이 없어야합니다.

완전히 다른 리소스 (인보이스 대신 인보이스 컬렉션)를 반환하는 것은 잘못되었지만 같은 리소스에 대해 여러 가지 표현을 사용하는 것이 좋습니다. "수락"헤더가 없으면 서버는 하나를 선택하거나 406 Not Acceptable을 표시해야합니다.

하나의 작은 점 : 마임 유형은 application/json이 아니어야합니다. 그 이유는 인보이스라는 것을 어떻게 알기 때문입니다. 다음과 같아야합니다 : application/vnd.someprovider.invoice+json. 요즘에는 아무도 마임 (mime) 유형을 귀찮게하지 않지만 완벽을 기하기 위해 언급합니다.