HTTP
API를위한 HTTP

Android Angular 2 AngularJS C# Language HTML Java Language JavaScript Node.js PHP Python Language
수색…


비고

HTTP API는 광범위한 HTTP 동사를 사용하며 일반적으로 JSON 또는 XML 응답을 반환합니다.

리소스 만들기

자원 창출을위한 가장 의미 론적으로 올바른 방법에 대해 모두가 동의하는 것은 아닙니다. 따라서 API는 POST 또는 PUT 요청을 수락 할 수 있습니다.

자원이 성공적으로 작성된 경우 서버는 201 Created 응답해야합니다. 그렇지 않은 경우 가장 적합한 오류 코드를 선택하십시오.

예를 들어, 직원 레코드를 작성하는 API를 제공하면 요청 / 응답이 다음과 같이 보일 수 있습니다. 

POST /employees HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Charlie Smith",
    "age": 38,
    "job_title": "Software Developer",
    "salary": 54895.00
}

HTTP/1.1 201 Created
Location: /employees/1/charlie-smith
Content-Type: application/json

{
    "employee": {
        "name": "Charlie Smith",
        "age": 38,
        "job_title": "Software Developer",
        "salary": 54895.00
        "links": [
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "self",
                "method": "GET"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "delete",
                "method": "DELETE"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "edit",
                "method": "PATCH"
            }
        ]
    },
    "links": [
        {
            "uri": "/employees",
            "rel": "create",
            "method": "POST"
        }
    ]
}

응답에 JSON 필드 links 포함 시키면 클라이언트는 URI 나 메소드를 미리 알 필요없이 새로운 리소스 및 애플리케이션 전체와 관련된 리소스에 액세스 할 수 있습니다.

자원 편집

API의 일반적인 목적은 리소스를 수정하거나 업데이트하는 것입니다. POST , PUT 또는 PATCH 요청을 각각의 리소스로 전송하여 편집 할 수 있습니다. POST 는 자원의 기존 표현에 데이터를 추가 할 수 있지만 더 명확한 의미를 전달할 때 PUT 또는 PATCH 를 사용하는 것이 좋습니다.

서버는 업데이트가 수행되면 200 OK 응답해야하고, 아직 적용되지 않은 경우 202 Accepted 로 응답해야합니다. 완료 할 수없는 경우 가장 적절한 오류 코드를 선택하십시오.

전체 업데이트

PUT 은 현재 표현을 요청에 포함 된 페이로드로 대체하는 의미 PUT 집니다. 페이로드가 갱신 할 자원의 현재 표현과 동일한 표현 유형이 아닌 경우, 서 v는 취할 접근 f}을 결정할 수 있습니다. RFC7231 은 서버가

  • 새 미디어 유형을 반영하도록 대상 자원을 재구성하십시오.
  • 새로운 자원 상태로 저장하기 전에 PUT 표현을 자원의 형식과 일치하는 형식으로 변환하십시오.
  • 대상 자원이 특정 (세트의) 미디어 유형으로 제한된다는 것을 나타내는 415 Unsupported Media Type 응답으로 요청을 거부합니다.

JSON HAL 표현을 포함하는 기본 리소스 ... 

{
    "name": "Charlie Smith",
    "age": 39,
    "job_title": "Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

... 이와 같은 업데이트 요청을받을 수 있습니다. 

PUT /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 85
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

이제 서버가 리소스의 상태를 지정된 요청 본문으로 대체하고 content-type을 application/hal+json 에서 application/json 하거나 JSON 페이로드를 JSON HAL 표현으로 변환 한 다음 리소스의 내용을 바꿀 수 있습니다 415 Unsupported Media Type 응답을 가진 비공식 미디어 유형으로 인해 업데이트 요청을 거부하거나 거부 할 수 있습니다.

내용을 직접 바꾸거나 먼저 표현을 정의 된 표현 모델로 변환 한 다음 기존 내용을 변환 된 표현으로 바꾸는 것에는 차이가 있습니다. 후속 GET 요청은 직접 교체시 다음 응답을 반환합니다. 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

변환 및 대체 접근법은 다음과 같은 표현을 반환합니다. 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: e0023aa4e

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

부작용

PUT 은 멱수 (idempotent) 연산으로 정의되었지만 부작용이 허용된다는 점에 유의하십시오! 이것은 RFC7231에 문서화되어있다.

대상 자원에 적용된 PUT 요청 은 다른 자원에 부작용을 줄 수 있습니다 . 예를 들어 아티클은 각 특정 버전을 식별하는 URI와 분리 된 "현재 버전"(리소스)을 식별하기위한 URI를 가질 수 있습니다 (한 시점에서 현재 버전 리소스와 동일한 상태를 공유하는 다른 리소스). 따라서 "현재 버전"URI에 대한 PUT 요청이 성공하면 대상 자원의 상태를 변경하는 것 외에도 새로운 버전의 자원이 만들어지며 관련 자원간에 링크가 추가 될 수도 있습니다.

추가 로그 항목 작성은 대개 일반적인 자원 상태가 아니므로 부작용으로 간주되지 않습니다.

부분 업데이트

RFC7231 에서는 부분 업데이트와 관련 하여이 점을 언급합니다.

별도로 식별 된 리소스를 더 큰 리소스의 일부와 겹치는 상태로 대상 지정하거나 부분 업데이트에 대해 특별히 정의 된 다른 메서드 (예 : RFC5789에 정의 된 PATCH 메서드)를 사용하여 부분 콘텐츠 업데이트를 수행 할 수 있습니다.

따라서 부분 업데이트는 두 가지 방식으로 수행 될 수 있습니다.

겹치는 상태의 부분 업데이트

사용자를 직접 업데이트하는 대신 사용자 위치를 다른 위치로 이동하여 사용자 표현을 부분적으로 업데이트해야하는 경우 사용자 표현의 부분 업데이트에 반영되는 관련 리소스를 직접 업데이트해야합니다.

이동하기 전에 사용자는 다음과 같은 표현을 가졌습니다. 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Terrace Drive, Central Park",
            "zip": "NY 10024"
            "city": "New York",
            "country": "United States of America",
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=40.7739166,-73.970176" }
            }
        }
    }
}

사용자가 새로운 위치로 이동하면 그녀는 다음과 같이 자신의 위치 정보를 업데이트합니다. 

PUT /address/abc HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 109
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "street": "Standford Ave",
    "zip": "CA 94306",
    "city": "Pablo Alto",
    "country": "United States of America"
}

위에서 설명한 것처럼 기존 주소 자원과 요청에있는 주소 유형 간의 불일치 미디어 유형에 대한 대체 전 변환 의미론을 사용하면 주소 자원이 업데이트되어 사용자 자원에 대한 후속 GET 요청시 사용자에 대한 새 주소가 리턴됩니다. 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Standford Ave",
            "zip": "CA 94306",
            "city": "Pablo Alto",
            "country": "United States of America"
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=37.4241311,-122.1524475" }
            }
        }
    }
}

부분 데이터 패치

PATCH 에 정의되어 RFC5789 직접 HTTP 사양 자체의 일부가 아닙니다. 일반적인 불신은 부분적으로 업데이트해야하는 필드 만 보내는 것이 PATCH 요청으로 충분하다는 것 입니다. 따라서 사양은

PATCH 메소드는 요청 엔티티에 기술 된 변경 세트가 Request-URI에 의해 식별 된 자원에 적용되도록 요청한다. 변경 사항 집합은 미디어 유형으로 식별되는 "패치 문서"라는 형식으로 표시됩니다.

이는 클라이언트가 상태 A에서 상태 B로 자원을 변환하고 서버로 이러한 지시를 보내는 데 필요한 단계를 계산해야 함을 의미합니다.

패치 용으로 인기있는 JSON 기반 미디어 유형은 JSON 패치 입니다.

샘플 사용자의 나이와 직책이 변경되고 사용자 소득을 나타내는 추가 필드를 추가해야하는 경우 JSON 패치를 사용하여 PATCH 사용한 부분 업데이트가 다음과 같이 보일 수 있습니다. 

PATCH /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: application/json-patch+json; charset=utf-8
Content-Length: 188
Accept: application/json
If-Match: "e0023aa4e"

[
    { "op": "replace", "path": "/age", "value": 40 },
    { "op": "replace", "path": "/job_title", "value": "Senior Software Developer" },
    { "op": "add", "path": "/salery", "value": 63985.00 }
]

PATCH 는 여러 리소스를 동시에 업데이트 할 수 있으며 모든 변경 사항을 적용해야하거나 전혀 구현하지 않아 API 구현 자에게 트랜잭션 부담을주는 변경을 기본적으로 적용해야합니다.

성공적인 업데이트로 인해 다음과 같은 결과가 반환 될 수 있습니다. 

HTTP/1.1 200 OK
Location: /users/1234
Content-Type: application/json
ETag: "df00eb258"

{
    "name": "Charlie Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "salary": 63985.00
}

200 OK 응답 코드에만 국한되지는 않습니다.

중간 업데이트 (이전 상태의 표현 상태 가져 오기와 업데이트 사이에서 수행 된 변경)를 방지하려면 ETag , If-Match 또는 If-Unmodified-Since 헤더를 사용해야합니다.

오류 처리

PATCH 의 스펙은 다음 오류 처리를 권장합니다.

유형 에러 코드
조작 된 패치 문서 400 Bad Request
지원되지 않는 패치 문서 415 Unsupported Media Type
처리 할 수없는 요청, 즉 패치를 적용하여 resoure가 유효하지 않은 경우 422 Unprocessable Entity
리소스를 찾을 수 없음 404 Not Found
충돌하는 상태, 즉 존재하지 않는 필드의 이름 바꾸기 (이동) 409 Conflict
충돌 수정, 즉 클라이언트가 유효성 검사에 실패한 If-Match 또는 If-Unmodified-Since 헤더를 사용하는 If-Match 전제 조건을 사용할 수없는 경우 후자의 오류 코드가 반환되어야합니다. 412 Precondition Failed 또는 409 Conflict
동시 수정, 즉 추가 요청 전에 요청을 적용해야 할 경우 추가 PATCH 요청 409 Conflict

자원 삭제

HTTP API의 또 다른 일반적인 사용은 기존 자원을 삭제하는 것입니다. 이것은 대개 DELETE 요청을 사용하여 수행해야합니다.

삭제에 성공하면 서버에서 200 OK 반환해야합니다. 그렇지 않은 경우 적절한 오류 코드.

직원 인 Charlie Smith가 회사를 떠나고 이제는 그의 기록을 삭제하려고하면 다음과 같이 보일 수 있습니다. 

DELETE /employees/1/charlie-smith HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'links': [
        {
            'uri': '/employees',
            'rel': 'create',
            'method': 'POST'
        }
    ]
}

자원 목록 표시

HTTP API의 마지막 사용은 서버의 기존 자원 목록을 얻는 것입니다. 이와 같은 목록은 데이터 만 검색 하므로 GET 요청을 사용하여 가져와야 합니다.

서버는 목록을 제공 할 수 있으면 200 OK 반환하고 그렇지 않으면 적절한 오류 코드를 반환해야합니다.

그러면 직원 목록을 다음과 같이 작성할 수 있습니다. 

GET /employees HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'employees': [
        {
            'name': 'Charlie Smith',
            'age': 39,
            'job_title': 'Software Developer',
            'salary': 63985.00
            'links': [
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        },
        {
            'name': 'Donna Prima',
            'age': 30,
            'job_title': 'QA Tester',
            'salary': 77095.00
            'links': [
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        }
    ],
    'links': [
        {
            'uri': '/employees/new',
            'rel': 'create',
            'method': 'PUT'
        }
    ]
}


Modified text is an extract of the original Stack Overflow Documentation
아래 라이선스 CC BY-SA 3.0
와 제휴하지 않음 Stack Overflow