RESTful API Specifications

웨어 하우스는 현재 인기있는 RESTful API 디자인 사양을 구성합니다. 사양에 의해 초래 된 문제 및 분쟁에 대한 토론을 용이하게하기 위해 문서가 Github에서 호스팅되며, 추가 할 수 있습니다! !

 

"기꺼이 동사"의 사용에 관하여

모호성을 피하기 위해이 문서는 많은 수의 "기꺼이 동사"를 사용합니다. 해당 설명은 다음과 같습니다.

• 반드시 (MUST) : 절대적으로 엄격히 따라야하며, 그렇게하고, 무조건 따라야합니다.
• 절대 금지(MUST NOT) : 금지는 엄격히 금지되어 있습니다.
• 반드시 그렇게하는 것(SHOULD)이 좋지만 강력하지는 않은 것이 좋습니다.
• 하지 말아야 할 일(SHOULD NOT) : 그렇게하는 것이 매우 바람직하지 않지만 필수는 아닙니다.
• 예 (MAY) 및 선택 사항 (OPTIONAL) : 선택도가 높습니다.이 문서에서이 용어는 덜 사용됩니다.

RFC 2119를 참조하십시오.

 

Protocol

클라이언트는 API를 통해 백엔드 서비스와 통신 할 때 HTTPS 프로토콜을 사용해야합니다.

 

API Root URL

API의 루트 엔트리 포인트는 가능한 한 간단해야하며 다음 두 가지 URL 루트 예가 있습니다.

• Api.example.com/*
• Example.com/api/*

응용 프로그램이 매우 크거나 매우 큰 것으로 예상되는 경우 API를 하위 도메인 (api.example.com)에 배치해야합니다. 이 접근법은 일정한 유연성을 유지할 수 있습니다.

 

Versioning

모든 API는 이전 버전과 호환되어야하며 API의 새 버전을 소개하면서 이전 버전의 API를 계속 사용할 수 있어야합니다. 따라서 버전 지원을 제공해야합니다.

현재 두 가지 공통적 인 버전 번호 양식 :

 

URL에 버전 번호 포함

Api.example.com/v1/*
이것은 직관적 인 버전이며 디버깅하기 쉽습니다; 또 다른 방법은 버전 번호를 HTTP 헤더 헤더에 넣는 것입니다.

 

미디어 유형별 버전 정보 지정

Accept : application/vnd.example.com.v1+json
여기서 vnd는 표준 트리 표준 트리 유형을 나타내며 x, pns 및 vnd의 세 가지 트리가 있습니다. 사용하는 표준 트리는 개발중인 프로젝트에 따라 다릅니다.

•   등록되지 않은 트리(x)는 주로 지역 및 사적 환경을 나타냅니다.
•   프라이비트 트리 (prs)는 주로 상업적 프로젝트가 없음을 나타냅니다
•   공급 업체 트리 (vnd)는 주로 공개 된 프로젝트를 나타냅니다.

다음 몇 가지 매개 변수는 응용 프로그램 이름 (일반적으로 응용 프로그램 도메인 이름), 버전 번호 및 예상되는 반환 형식입니다.

버전 번호가있는 특정 위치에 대해서는 논란의 여지가 있지만 Laravel 개발을 대부분 사용하고 있으므로 dingo/api를 사용하여 응용 프로그램을 빠르게 작성해야하며 두 번째 방법으로 API를 관리해야합니다. 버전으로 통합되었으며 표준 HTTP 응답을 통합했습니다.

 

Endpoints

엔드 포인트는 특정 자원 또는 자원 콜렉션을 가리키는 URL입니다. 엔드 포인트 설계시 다음 규약을 준수해야합니다.

•   URL의 이름은 모두 소문자 여야합니다.
•   URL의 리소스 이름은 명사이어야하며 복수형이어야합니다.
•   Restful 유형의 URL에 우선 순위를 사용해야합니다.
•   URL은 읽을 수 있어야합니다.
•   URL은 서버 아키텍처를 폭로하지 않아야합니다.

URL이 하이픈(-) 또는 밑줄(_)을 사용해야하는지 여부는 어렵지 않고 빠르지만 스타일은 팀에 따라 통일되어야합니다.

반례표를 보세요.

• https://api.example.com/getUserInfo?userid=1
• https://api.example.com/getusers
• https://api.example.com/sv/u
• https://api.example.com/cgi-bin/users/get_user.php?userid=1

긍정적인 칼럼을 보아라.

• https://api.example.com/zoos
• https://api.example.com/animals
• https://api.example.com/zoos/{zoo}/animals
• https://api.example.com/animal_types
• https://api.example.com/employees

HTTP 동사

HTTP 동사로 표시되는 리소스에 대한 특정 유형의 작업입니다. 일반적으로 사용되는 HTTP 동사에는 다음 5 개가 있습니다 (괄호 안의 해당 SQL 명령).

• GET (SELECT) : 서버에서 리소스 (하나 이상)를 가져옵니다.
• POST (CREATE) : 서버에 새 자원을 작성하십시오.
• PUT (UPDATE) : 서버의 리소스를 업데이트합니다 (클라이언트는 변경된 전체 리소스를 제공합니다).
• PATCH (UPDATE) : 서버의 리소스를 업데이트합니다 (클라이언트가 변경된 특성을 제공함).
• DELETE (DELETE) : 서버에서 자원을 삭제합니다.

어느 쪽

1 자원 삭제 DELETE 메소드 2를 사용하여 새 자원을 작성해야합니다 POST 메소드를 사용해야합니다 3 PUT 메소드를 사용해야합니다 4 자원 정보를 얻으려면 GET 메소드를 사용해야합니다.

각 엔드 포인트에 대해 다음은 HTTP 동사와 엔드 포인트의 가능한 모든 조합을 나열합니다

 

요청 방법	URL	설명
GET	/zoos	모든 동물원을 나열하십시오 (ID와 이름, 너무 상세하지 마십시오)
POST	/zoos	새 동물원 추가
GET	/zoos/{zoo}	특정 동물원 정보 얻기
PUT	/zoos/{zoo}	지정된 동물원 업데이트 (전체 개체)
PATCH	/zoos/{zoo}	동물원 업데이트 (객체의 일부)
DELETE	/zoos/{zoo}	지정된 동물원 삭제
GET	/zoos/{zoo}/animals	지정된 동물원의 동물 목록을 찾으십시오 (ID와 이름, 너무 자세하지 않음).
GET	/animals	모든 동물 (ID 및 이름)을 나열하십시오.
POST	/animals	새 동물 추가
GET	/animals/{animal}	지정된 동물 정보 얻기
PUT	/animals/{animal}	지정된 동물 업데이트 (전체 객체)
PATCH	/animals/{animal}	지정된 동물 (부분 객체) 업데이트
GET	/animal_types	모든 동물 유형을 얻으십시오 (ID와 이름, 너무 상세하지 마십시오).
GET	/animal_types/{type}	지정된 동물 유형 정보 얻기
GET	/employees	전체 직원 목록 검색
GET	/employees/{employee}	특정 직원 검색
GET	/zoos/{zoo}/employees	이 동물원에서 일하는 직원 목록 (신원과 이름)을 검색하십시오.
POST	/employees	새 지정 직원 추가
POST	/zoos/{zoo}/employees	특정 동물원 직원 고용
DELETE	/zoos/{zoo}/employees/{employee}	동물원에서 직원 퇴직

 

Restful endpoint를 넘어서는 endpoint는 위의 표와 같은 방법으로 정의되어야한다.

 

Filtering

레코드 수가 많으면 서버가 사용자에게 레코드를 반환하지 않을 수 있습니다. API는 매개 변수를 제공하고 결과를 다시 필터링해야합니다. 다음은 일반적인 매개 변수입니다.

• ?limit=10 : 반환되는 레코드 수 지정
• ?offset=10 : 반환 된 레코드의 시작 위치를 지정합니다.
• ?page=2&per_page=100 : 처음 몇 페이지와 페이지 당 레코드 수를 지정하십시오.
• ?sortby=name&order=asc : 반환 된 결과가 정렬되는 특성과 정렬 순서를 지정합니다.
• ?animal_type_id=1 : 필터 기준 지정

모든 URL 매개 변수는 모두 소문자 여야하며 밑줄 유형의 매개 변수 형식이어야합니다.

Page 매김 매개 변수는 per_page 페이지로 고정되어야합니다.

유지 관리 비용을 줄이기 위해 자주 사용되는 복잡한 쿼리에 태그를 지정해야합니다. 예 :

GET /trades?status=Closed&sort=sortby=name&order=asc

# 그것에 대한 단축키를 사용자 정의 할 수 있습니다.
GET / trades/ recent_closed

 

Authentication

OAuth2.0을 사용하여 API 호출자에게 로그인 자격 증명을 제공해야합니다. 액세스 토큰은 토큰을 통한 인증이 필요한 API를 호출하기 전에 로그인 인터페이스를 통해 확보해야합니다.

Oauth의 엔드 포인트 디자인

• RFC 6749 /token
• Twitter /oauth2/token
• Fackbook /oauth/access_token
• Google /o/oauth2/token
• Github /login/oauth/access_token
• Instagram /oauth/authorize

클라이언트가 액세스 토큰을 확보하면 응답에 expires_in이라는 이름의 데이터가 포함되어야합니다. 이 데이터는 현재 획득된 토큰이 만료되는 시간 (초)을 나타냅니다.

{
    "access_token": "token....",
    "token_type": "Bearer",
    "expires_in": 3600
}

클라이언트가 인증이 필요한 API를 요청하면, 클라이언트는 요청 헤더 Authorization에 access_token을 포함시켜야합니다.

 

Authorization: Bearer token...

 

지정된 시간 (초)을 초과하면 액세스 토큰이 만료되고 만료 / 유효하지 않은 토큰을 다시 액세스하면 서버가 invalid_token 오류 또는 401 오류 코드를 반환해야합니다.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "error": "invalid_token"
}

Laravel 개발에서는 JWT를 사용하여 토큰을 관리해야하며 API 미들웨어에서 요청 세션을 열지 않아야합니다.

 

Response

모든 API 응답은 HTTP 디자인 사양을 준수해야하며 적절한 HTTP 상태 코드를 선택해야합니다. 물론 모든 인터페이스는 다음과 같이 상태 코드가 200 인 HTTP 응답을 반환합니다.

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "code": 0,
    "msg": "success",
    "data": {
        "username": "username"
    }
}

또는

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "code": -1,
    "msg": "This activity does not exist",
}

다음 표는 일반적인 HTTP 상태 코드를 나열합니다.

상태 코드	설명
1xx	대표 요청이 수락되어 처리해야합니다.
2xx	요청이 성공했으며 요청에 필요한 응답 헤더 또는 데이터 본문이이 응답과 함께 반환됩니다.
3xx	리다이렉션
4xx	클라이언트에서 발생한 오류
5xx	서버 측 오류

클라이언트의 요청이 올바르게 처리 될 때만 2xx의 응답이 리턴 될 수 있으므로 API가 유형 2xx의 상태 코드를 리턴 할 때 프론트 엔드는 요청이 성공적으로 처리되었다고 가정해야합니다.

 

모든 API가 유형 1xx의 상태 코드를 리턴해서는 안된다는 점을 강조해야합니다. API에서 오류가 발생하면 오류가 발생했을 때 세부 정보를 반환해야합니다. 오류 메시지를 반환하는 일반적인 두 가지 방법은 다음과 같습니다.

 

1. HTTP 응답 헤더에 오류를 자세하게 넣습니다.

X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication

 

2. 응답 개체로 직접;

HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive

{"error_code":40100,"message":"Unauthorized"}

 

가독성과 클라이언트 조작성을 고려하여 오류 정보를 응답 엔터티에 직접 넣어야하며 오류 형식은 다음 형식을 만족해야합니다.

 

{
    "message": "찾고있는 리소스가 존재하지 않습니다",
    "error_code": 404001
}

오류 코드 (error_code)는 HTTP 상태 코드와 일치해야하며 다음과 같은 오류 코드 분류에도 편리합니다.

HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:15:52 GMT
Connection: keep-alive

{"error_code":429001,"message":"너무 자주 운영됩니다"}

 

HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:19:27 GMT
Connection: keep-alive

{"error_code":403002,"message":"사용자가 사용 중지되었습니다"}

 

반환 된 오류 메시지에는 개발자 지향 및 사용자 지향 프롬프트 정보가 모두 포함되어야하며 전자는 개발자가 쉽게 디버깅 할 수 있으며 최종 사용자는 다음과 같은 최종 사용자에게 직접 표시 할 수 있습니다.

 

{
     "message": "최종 사용자에게 직접 표시되는 오류 메시지",
     "error_code": "비즈니스 오류 코드",
     "error": "개발자가 볼 수있는 오류 메시지",
     "디버그": [
         "오류 스택, 디버그가 존재하도록 설정되어 있어야합니다"
     ]
}

 

다음은 다양한 시나리오에 대한 반환 지침에 대한 자세한 설명입니다.

 

200 ok

200 상태 코드는 가장 일반적인 HTTP 상태 코드이며 모든 성공적인 GET 요청에서 반환되어야합니다. HTTP 응답 엔터티 부분은 중복 패키징이 아닌 직접 데이터 여야합니다.

오류 예 :

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "user": {
        "id":1,
        "nickname":"fwest",
        "username": "example"
    }
}

올바른 예 :

1. 개별 리소스 세부 정보 얻기

{
    "id": 1,
    "username": "godruoyi",
    "age": 88,
}

2. 리소스 컬렉션 가져 오기

[
    {
        "id": 1,
        "username": "godruoyi",
        "age": 88,
    },
    {
        "id": 2,
        "username": "foo",
        "age": 88,
    }
]

3. 추가 미디어 정보

{
    "data": [
        {
            "id": 1,
            "avatar": "https://lorempixel.com/640/480/?32556",
            "nickname": "fwest",
            "last_logined_time": "2018-05-29 04:56:43",
            "has_registed": true
        },
        {
            "id": 2,
            "avatar": "https://lorempixel.com/640/480/?86144",
            "nickname": "zschowalter",
            "last_logined_time": "2018-06-16 15:18:34",
            "has_registed": true
        }
    ],
    "meta": {
        "pagination": {
            "total": 101,
            "count": 2,
            "per_page": 2,
            "current_page": 1,
            "total_pages": 51,
            "links": {
                "next": "http://api.example.com?page=2"
            }
        }
    }
}

그 중에서도 페이지 매김 및 기타 추가 미디어 정보를 메타 필드에 배치해야합니다.

201 Created

서버가 데이터를 성공적으로 만들면이 상태 코드가 반환되어야합니다. 일반적인 응용 프로그램 시나리오는 다음과 같이 POST를 사용하여 사용자 정보를 제출하는 것입니다.

• 새 사용자 추가
• 업로드 된 이미지
• 새 일정 만들기

등등. 201 상태 코드로 돌아갈 수 있습니다. 사용자가 성공적으로 생성 된 후에는 새 사용자의 데이터를 반환하도록 선택할 수 있습니다.

HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:13:40 GMT
Connection: keep-alive

{
    "id": 1,
    "avatar": "https:\/\/lorempixel.com\/640\/480\/?32556",
    "nickname": "fwest",
    "last_logined_time": "2018-05-29 04:56:43",
    "created_at": "2018-06-16 17:55:55",
    "updated_at": "2018-06-16 17:55:55"
}

다음과 같이 응답 엔터티가 비어있는 HTTP 응답을 반환 할 수도 있습니다.

HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:12:20 GMT
Connection: keep-alive

대부분의 경우 클라이언트는 요청 작업이 성공했는지 여부만 알 필요가 있고 새 리소스에 대한 정보를 반환할 필요가 없으므로 두 번째 방법을 사용해야합니다.

202 Accepted

상태 코드는 서버가 클라이언트로부터 요청을 받았지만 아직 처리를 시작하지 않았 음을 나타냅니다. 일반적으로 사용되는 SMS 전송, 전자 메일 알림, 템플릿 메시지 푸시 등은 시간 소모적이며 대기열 지원이 필요합니다.

이 상태 코드를 반환 할 때 응답 엔터티는 비어 있어야합니다.

HTTP/1.1 202 Accepted
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:25:15 GMT
Connection: keep-alive

204 No Content

상태 코드는 응답 엔터티가 데이터를 포함하지 않음을 나타냅니다.

• DELETE 메서드를 사용하여 리소스를 성공적으로 삭제하면 상태 코드를 반환해야합니다.
• 이 데이터는 PUT 및 PATCH 메소드를 사용하여 데이터가 성공적으로 갱신 될 때 리턴되어야합니다.

HTTP/1.1 204 No Content
Server: nginx/1.11.9
Date: Sun, 24 Jun 2018 09:29:12 GMT
Connection: keep-alive

3xx Redirection

모든 API는 3xx 유형의 상태 코드를 반환하지 않아야합니다. 3xx 유형의 응답 형식은 일반적으로 다음 형식입니다.

HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 09:41:50 GMT
Location: https://example.com
Connection: keep-alive

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta http-equiv="refresh" content="0;url=https://example.com" />

        <title>Redirecting to https://example.com</title>
    </head>
    <body>
        Redirecting to <a href="https://example.com">https://example.com</a>.
    </body>
</html>

모든 API는 순수한 HTML 구조에 대한 응답을 반환해서는 안되며, 리디렉션 함수를 사용해야하는 경우 응답 헤더에 null 응답 본문과 Location 필드가있는 3xx 응답을 반환 할 수 있습니다.

HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:52:50 GMT
Location: https://godruoyi.com
Connection: keep-alive

400 Bad Request

서버는 분명한 클라이언트 오류 (예 : 요청 구문 오류, 잘못된 요청, 잘못된 서명 등)로 인해 요청을 포기해야합니다.

서버가 다른 4xx 유형의 상태 코드에서 적절한 유형의 오류를 찾을 수 없으면 상태 코드를 리턴해야합니다.

HTTP/1.1 400 Bad Request
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:22:36 GMT
Connection: keep-alive

{"error_code":40000,"message":"잘못된 서명"}

401 Unauthorized

이 상태 코드는 현재 요청에 인증이 필요함을 나타내며 다음과 같은 경우 상태 코드가 반환되어야합니다.

• 인증이 필요한 인증되지 않은 사용자 액세스 API
• 무효/만료 된 Access_token

401 응답을 수신 한 후, 클라이언트는 다음 로그인 조작을 위해 사용자에게 프롬프트해야합니다.

HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
WWW-Authenticate: JWTAuth
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:17:02 GMT
Connection: keep-alive

{"message":"Token Signature could not be verified.","error_code": "40100"}

 

403 Forbidden

상태 코드는 단순히 요청에 대한 액세스 권한이없는 것으로 이해 될 수 있으며 서버는 요청을 수신하지만 서비스 제공을 거부합니다.

예를 들어 일반 사용자가 관리자 사용자를 요청하면 상태 코드를 반환해야합니다.

HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:05:34 GMT
Connection: keep-alive

{"error_code":40301,"message":"권한 부족"}

 

404 Not Found

상태 코드는 사용자가 요청한 리소스가 존재하지 않음을 나타냅니다.

• 존재하지 않는 사용자 정보 가져 오기 (get/users/9999999)
• 존재하지 않는 엔드 포인트 액세스

두 가지 모두 상태 코드를 반환해야하며 리소스가 영구적으로 존재하지 않으면 410 응답을 반환해야합니다.

405 Method Not Allowed

이 상태 코드는 클라이언트가 사용하는 HTTP 요청 방법이 서버에 허용되지 않은 경우 반환되어야합니다.

클라이언트가 POST 메서드를 호출하여 GET 메서드 만 지원하는 API에 액세스하는 경우

응답은 현재 자원이 승인 할 수있는 요청 메소드 목록을 표시하기 위해 Allow 헤더를 리턴해야합니다.

HTTP/1.1 405 Method Not Allowed
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Allow: GET, HEAD
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:30:57 GMT
Connection: keep-alive

{"message":"405 Method Not Allowed","error_code": 40500}

 

406 Not Acceptable

API는 클라이언트가 지정한 데이터 형식을 지원하지 않을 때이 상태 코드를 반환해야합니다. JSON 및 XML 출력을 지원하는 API가 YAML 형식의 데이터를 반환하도록 지정된 경우.

Http 프로토콜은 일반적으로 헤더의 수락을 요청하여 데이터 형식을 지정합니다.

408 Request Timeout

클라이언트 요청 시간이 초과되면 상태 코드를 반환해야하며,주의가 필요한 경우 상태 코드는 클라이언트 요청 시간이 초과되었음을 나타냅니다. 타사 API 호출 시간 초과가 발생하면 상태 코드를 반환하지 않아야합니다.

409 Confilct

이 상태 코드는 충돌로 인해 요청을 처리하지 못했음을 나타냅니다. 등록 용 API가 휴대 전화 번호로 제공되는 경우 사용자가 제출 한 휴대 전화 번호가 이미 존재하는 경우이 상태 코드를 반환해야합니다.

HTTP/1.1 409 Conflict
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:19:04 GMT
Connection: keep-alive

{"error_code":40900,"message":"휴대 전화 번호가 이미 있습니다"}

410 Gone

404와 마찬가지로 상태 코드는 요청 된 리소스가 존재하지 않지만 410 상태 코드는 요청 된 리소스가 더 이상 존재하지 않으며 향후에 존재하지 않을 것임을 나타냅니다. 410 상태 코드를 수신 한 후 클라이언트는 자원 요청을 다시 중지해야합니다.

413 Request Entity Too Large

상태 코드는 요청으로 제출 된 엔티티 데이터의 크기가 서버가 처리 할 수 있거나 허용 할 수있는 범위를 초과하여 서버가 현재 요청을 처리하기를 거부했음을 나타냅니다.

이 경우 서버는 클라이언트가이 요청을 계속 보내지 못하도록 연결을 닫을 수 있습니다.

이 조건이 일시적인 경우 서버는 Retry-After 응답 헤더를 반환하여 나중에 재 시도 할 시간을 클라이언트에 알려야합니다.

414 Request-URI Too Long

상태 코드는 요청 된 URI 길이가 서버가 해석 할 수있는 길이를 초과하므로 서버가 요청을 처리하기를 거부 함을 나타냅니다.

415 Unsupported Media Type

일반적으로 서버가 클라이언트 요청 헤더 Content-Type에 의해 지정된 데이터 형식을 지원하지 않음을 나타냅니다. JSON 형식 만 허용하는 API에 XML 형식 데이터를 저장하고 서버로 보내면 상태 코드를 반환해야합니다.

예를 들어 이미지 형식 파일 만 업로드 할 수 있도록 상태 코드를 사용할 수도 있지만 클라이언트가 미디어 파일을 불법적으로 제출하거나 이미지 유형을 제출하지 않는 경우이 경우 상태 코드가 반환되어야합니다.

HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:09:40 GMT
Connection: keep-alive

{"error_code":41500,"message":"업로드 할 수없는 이미지 형식"}

429 Too Many Requests

이 상태 코드는 사용자 요청 수가 허용되는 범위를 초과 함을 나타냅니다. API를 60 회 / 분으로 설정하면 사용자가 1 분 안에 60 회 이상 요청한 후에 상태 코드를 반환해야합니다. 그리고 응답 헤더에 다음 헤더를 추가해야합니다.

X-RateLimit 제한 : 요청 비율 10 (응용 프로그램에 의해 설정되며, 단위는 보통시 / 분 등이며, 여기서 10 회 / 5 분입니다)
X-RateLimit-Remaining : 0 현재 요청 수가 남아 있습니다.
X-RateLimit-Reset : 1529839462 재설정 시간
재시도 - 후 : 120 다음 액세스가 대기해야하는 시간 (초)

 

HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive

{"message":"You have exceeded your rate limit.","error_code":42900}

모든 API에 대해 속도 제한 지원을 설정해야합니다.

500 Internal Server Error

이 상태 코드는 서버 오류가 발생할 때 발생해야하며 500 개의 오류가 모두 발생하면 전체 오류 메시지 지원이 제공되고 추적 디버깅이 편리해야합니다.

503 Service Unavailable
상태 코드는 서버가 일시적으로 사용할 수없는 상태를 처리 함을 나타내며 서버가 유지 관리가 필요하거나 타사 API 요청 시간 초과 / 연결할 수없는 경우 상태 코드가 반환되어야합니다. API 서비스가 활발히 닫히면 응답 헤더를 Retry- After 헤더는 다시 액세스 할 수있는 시간 (초)을 나타냅니다.

HTTP/1.1 503 Service Unavailable
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:56:20 GMT
Retry-After: 60
Connection: keep-alive

{"error_code":50300,"message":"서비스 유지 보수"}

 

다른 HTTP 상태 코드는 HTTP 상태 코드 - 위키피디아를 참조하십시오.

 

저작권 진술

저작권 공지 : 무료 재판본 - 비영리 - 비 파생적 - 서명 유지 (Creative Share 3.0 라이센스)

 

추천 참조

restful-api-design-references

Principles of good RESTful API Design（번역）

RESTful 아키텍처 이해

RESTful API 디자인 가이드

HTTP 상태 코드 - Wikipedia