Creating and providing a state of the art API requires taking into account
(API의 상태를 만들고 제공하는 것은 다음을 고려한다)
-
RESTful API principles as described in the literature (Roy Fielding, Martin Fowler, HTTP specification…)
-
The API practices of the Web Giants like Google, Microsoft, Facebook, PayPal, and other big companies.
-
문헌에 묘사된 RESTful API의 원칙
-
큰 기업의 API 사례
RESTful API를 만드는 5가지 원칙
- Resources (URIs)
- HTTP methods
- HTTP headers
- Query parameters
- Status Codes
1. Resources (URIs) Names and Verbs
(Resources 이름과 동사)
Resources를 설명하려면 동작 동사가 아닌 구체적인 이름을 사용해라
수십년동안 컴퓨터 과학자들은 RPC 방식으로 서비스를 노출하기 위해 액션 동사를 사용했다
(getUser(1234) createUser(user) deleteAddress(1234))
By contrast, the RESTful approach is to use
이와 대조적으로, RESTful 접근 사용법
(GET /users/1234 POST /users (with JSON describing a user in the body) DELETE /addresses/1234)
URI case
CamelCase,
snake_case,
spinal-case의
세 가지 주요 유형의 규칙이 있다
CamelCase
카멜케이스는 자바어에 의해 대중화되었다
E.g. camelCase, currentUser
Aside from debates about its readability, its main drawback is to be ineffective in contexts that are not case sensitive.
(가독성 외에 대소문자를 구분하지 않는 맥락에서 비효과적이라는 것)
snake_case
snakecase는 수년간 C 프로그래머들에 의해 널리 사용되어 왔으며 최근에는 루비에서 더 많이 사용되고 있다
단어는 underscores ""로 구분되므로 컴파일러나 해석자가 하나의 기호로 이해할 수 있을 뿐 아니라 독자가 단어를 유창하게 구분할 수 있다
하지만 이름이 너무 길거나 짧은 C프로그램에서 악용되는 경우가 많아 인기가 떨어졌다. CamelCase와 달리, snake_case는 사용할 수 없는 문맥이 거의 없다. 예: snake_case, current_user 등
spinal-case
spinal-case는 단어를 구분하기 위해 hyphens "-"를 사용하는 snake_case의 변형이다
일부 언어에서는 symbol names(for variable, class, or function naming)에 hyphens을 사용할 수 없다는 점을 제외하고는 장단점이 snake_case와 상당히 유사하다
Lisp dialects에서 변수와 함수의 이름을 지정하는 일반적인 방법이기 때문에 lisp-case라고 할 수 있다
UNIX 및 Linux 시스템에서 폴더와 파일의 이름을 지정하는 전통적인 방식이기도 하다 Examples: spinal-case, current-user, etc.
RFC3986에 따라서, URL들은 "대소문자를 구분"합니다(except for the scheme and the host).
그러나 실제로는 중요한 경우 Windows 시스템에서 호스트되는 API로 인해 장애가 발생할 수 있다
It is recommended to use the spinal-case (which is highlighted by RFC3986), this case is used by Google, PayPal, and other big companies.
2. HTTP methods
REST 접근방식의 주요 목표 중 하나는 직접 만든 API를 변형하는 것을 피하기 위해 HTTP를 응용 프로토콜로 사용하는 것이다.
따라서 HTTP 동사를 체계적으로 사용하여 자원에 대해 어떤 조치를 수행하는지 설명하고 개발자의 반복적인 CRUD 작업을 용이하게 처리해야 한다
GET
The GET method is used to retrieve information from the given server using a given URI.
Requests using GET should only retrieve data and should have no other effect on the data.
HEAD
Same as GET, but transfers the status line and header section only.
POST
A POST request is used to send data to the server, for example, customer information, file upload, etc. using HTML forms.
PUT
Replaces all current representations of the target resource with the uploaded content.
PATCH
It is used to make minor updates to resources and it’s not required to be idempotent.
DELETE
Removes all current representations of the target resource given by a URI.
OPTIONS
Describes the communication options for the target resource.
Differences between PUT and PATCH
APUT request will replace the entire content of the resource at the location while a PATCH request, on the other hand, is used to make changes to a part of the resource at a location.
3. HTTP headers
HTTP 헤더는 요청 또는 응답 또는 메시지 본문에서 보낸 개체에 대한 필수 정보를 제공한다
General Header
These header fields have general applicability for both request and response messages.
Client Request Header
These header fields have applicability only for request messages.
Server Response Header
These header fields have applicability only for response messages.
Entity Header
These header fields define meta-information about the entity-body or, if no BODY is present, about the resource identified by the request.
4. Query parameters
Paging
Filtering
Sorting
Searching
5. Status Codes
200 – OK
Everything is working
201 – CREATED
A new resource has been created
204 – NO CONTENT
The resource was successfully deleted, no response body
304 – NOT MODIFIED
The date returned is cached data (data has not changed)
400 – BAD REQUEST
The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid “.
401 – UNATHORIZED
The request requires user authentication.
403 – FORBIDDEN
The server understood the request but is refusing it or the access is not allowed.
404 – NOT FOUND
There is no resource behind the URI.
500 – INTERNAL SERVER ERROR
API developers should avoid this error. If an error occurs in the global catch blog, the stack trace should be logged and not returned as a response.
