Rest Api 규칙 | [Api]3. Rest Api개념, 구성요소, Url설계규칙, Rest Client, Api사용 실습 최근 답변 270개

당신은 주제를 찾고 있습니까 “rest api 규칙 – [API]3. REST API개념, 구성요소, URL설계규칙, REST Client, API사용 실습“? 다음 카테고리의 웹사이트 you.tfvp.org 에서 귀하의 모든 질문에 답변해 드립니다: you.tfvp.org/blog. 바로 아래에서 답을 찾을 수 있습니다. 작성자 퉁퉁코딩TungTungCoding 이(가) 작성한 기사에는 조회수 23,647회 및 좋아요 474개 개의 좋아요가 있습니다.

REST에는 여섯 가지의 기본 원칙이 있고, 이 가이드를 준수한 인터페이스는 RESTful 하다고 표현한다. Stateless(무상태성) – 클라이언트의 모든 요청에는 해당 요청을 이해할 수 있는 모든 정보가 포함되어야한다. 서버는 HTTP 요청에 대한 어떤 것도 저장하지 않는다.

rest api 규칙 주제에 대한 동영상 보기

여기에서 이 주제에 대한 비디오를 시청하십시오. 주의 깊게 살펴보고 읽고 있는 내용에 대한 피드백을 제공하세요!

d여기에서 [API]3. REST API개념, 구성요소, URL설계규칙, REST Client, API사용 실습 – rest api 규칙 주제에 대한 세부정보를 참조하세요

1. REST API
– 정의
– 구성요소
– 키 발급
– developer console
2. API 사용
– google Books API
– YTS movies API
– 카카오 Maps API
– 알라딘 Open API
3. API 테스트 도구
– VSCode Rest Client Extension
– Insomnia Rest Client
|이미지|영상|
https://placeit.net/
https://pixabay.com/ko/videos/

rest api 규칙 주제에 대한 자세한 내용은 여기를 참조하세요.

REST API URI 규칙 – velog

REST API URI를 결정하는 몇가지 규칙 · 1. 소문자를 · 2. 언더바대신 하이픈을 사용한다. · 3. URI의 마지막에는 슬래시를 포함하지 않는다. · 4. 계층관계를 …

+ 자세한 내용은 여기를 클릭하십시오

Source: velog.io

Date Published: 6/30/2022

View: 893

[REST API] URL 규칙, RESTful한 URL이란? – 튜나 개발일기

[REST API] URL 규칙, RESTful한 URL이란? · 1. 소문자를 사용한다. · 2. 언더바를 대신 하이픈을 사용한다. · 3. 마지막에 슬래시를 포함하지 않는다. · 4.

+ 자세한 내용은 여기를 클릭하십시오

Source: devuna.tistory.com

Date Published: 9/23/2021

View: 121

REST API 설계 (네이밍) – 임대리 개발일지

이번 기회에 RESTful한 API 네이밍 방법을 정리하여 필자의 전두엽에 평안을 주기위해 이 글을 작성한다. 목차. 1. REST란? 2. Resource 표현방식. 3.

+ 여기에 자세히 보기

Source: server-engineer.tistory.com

Date Published: 4/9/2022

View: 7201

REST API 규칙 – IBM

IBM® UrbanCode Release REST API는 안정적인 상호작용을 위해 규칙 세트를 준수합니다. REST URL. 서버의 각 요소 유형은 복수 양식을 사용하는 최상위 레벨 URL로 표시 …

+ 여기에 표시

Source: www.ibm.com

Date Published: 1/29/2022

View: 2765

RESTful API 설계 규칙 – One IT’s Devlog

1. REST API 기본규칙 · 주로 쓰는 Method. GET: 조회 (받겠다); POST: 리소스 생성 (보내겠다) · 나머지 Method. HEAD: GET과 유사하나 HTTP 메시지 헤더만 …

+ 여기에 더 보기

Source: one-it.tistory.com

Date Published: 4/18/2021

View: 7466

REST API URI의 7가지 규칙 – 알씨타운

REST API URI의 규칙에 대해 알아보기 전에 용어에 대해 간략히 짚고 넘어가도록 하겠습니다. URI. REST API는 URL를 사용합니다.

+ 더 읽기

Source: softlabsblog.tistory.com

Date Published: 5/25/2021

View: 8593

RESTful API의 URL 작성 규칙

REST API란? REST(Representational State Transfer)는 HTTP 네트워크 상의 리소스(Resource, 자원)를 정의하고 해당 리소스를 URI라는 고유의 주소로 …

+ 여기에 더 보기

Source: itvillage.tistory.com

Date Published: 3/16/2021

View: 2517

RESTful API 의미와 설계 규칙 – 코딩 공부 일지

4. REST API 설계 Rulse 및 예시 · 1. 소문자를 사용한다. · 2. 언더바( _ ) 대신 하이픈( – )을 사용한다. · 3. 마지막에 슬래시를 포함하지 않는다. · 4.

+ 여기에 자세히 보기

Source: cocoon1787.tistory.com

Date Published: 12/5/2021

View: 3259

RESTful API 설계 가이드 – 이상학의 개발블로그

일부 규칙들은 기존에 존재하는 회사 규칙 때문에 보편적인 REST API의 철학과 다를 수 있다. RESTful API 설계 가이드 심화 과정.

+ 여기에 자세히 보기

Source: sanghaklee.tistory.com

Date Published: 3/21/2021

View: 990

주제와 관련된 이미지 rest api 규칙

주제와 관련된 더 많은 사진을 참조하십시오 [API]3. REST API개념, 구성요소, URL설계규칙, REST Client, API사용 실습. 댓글에서 더 많은 관련 이미지를 보거나 필요한 경우 더 많은 관련 기사를 볼 수 있습니다.

---

주제에 대한 기사 평가 rest api 규칙

• Author: 퉁퉁코딩TungTungCoding
• Views: 조회수 23,647회
• Likes: 좋아요 474개
• Date Published: 2020. 4. 19.
• Video Url link: https://www.youtube.com/watch?v=X4DezEXbc5o

RESTful API를 위한 6가지 원칙과 네이밍

REST와 RESTful

REST는 REpresentational State Transfer 의 약어로, 클라이언트과 서버가 데이터를 주고 받는 방식에 대한 아키텍처 스타일이다. REST에는 여섯 가지의 기본 원칙이 있고, 이 가이드를 준수한 인터페이스는 RESTful 하다고 표현한다.

Client–server 구조 – 클라이언트와 서버는 서로 독립적이어야 하며, 클라이언트는 오직 URIs 리소스만 알아야한다. 클라이언트와 서버의 인터페이스가 변경되지 않는 한, 이 둘은 독립적으로 개발되거나 대체될 수 있게 유지해야한다. (관심사의 명확한 분리) Stateless(무상태성) – 클라이언트의 모든 요청에는 해당 요청을 이해할 수 있는 모든 정보가 포함되어야한다. 서버는 HTTP 요청에 대한 어떤 것도 저장하지 않는다. 컨텍스트를 유지해야하는 세션, 인증과 인가에 대한 정보 또한 클라이언트에만 보관되며, 각 요청 시 해당 정보를 모두 포함하여 서버에 요청한다. Cacheable – 서버는 Response cache-control 헤더에 해당 요청이 캐싱이 가능한 지에 대한 여부를 제공해야 한다. 이를 제공한다면 클라이언트는 Response를 캐싱하여 서버와 클라이언트 간의 상호작용을 줄이고, 성능과 서버 가용성을 늘릴 수 있다. Uniform interface(일관된 인터페이스) – 보편적인 소프트웨어 엔지니어링 원칙을 component interface 에 적용하면, 전체적인 시스템 아키텍처는 단순화되고 각 상호작용에 대한 가시성이 개선된다. 이름 그대로 일관된 인터페이스를 얻기 위해 REST에서는 4가지 인터페이스 규칙을 정의하였다. identification of resources : 요청 시 개별 자원을 식별할 수 있어야함

manipulation of resources through representations : 어떤 자원에 대헤 작업하기 위한 적절한 표현과 메타데이터를 충분히 갖추고 있다면, 서버는 해당 자원을 변경, 삭제할 수 있는 정보를 가지고 있단 의미

self-descriptive messages : 자신을 어떻게 처리해야하는지 정보를 포함해야함

hypermedia as the engine of application state : 단순히 결과 뿐만이 아니라 결과에 대한 정보를 포함해야 함 Layered system(다중 계층) – REST는 다중 계층 구조를 가질 수 있도록 허용한다. (예를 들어 API 서버와 DB서버 그리고 인증 서버를 따로 둘 수 있도록). 그리고 각 레이어는 자기와 통신하는 컴포넌트 외 레이어에 대해서는 정보를 얻을 수 없다. 클라이언트는 REST 서버와만 상호작용할 뿐, REST가 상호작용하는 레이어나 그 외 중간 레이어들, end server에 직접적으로 요청할 수 없으며 이들의 상호작용 또한 볼 수 없다. Code on demand (optional) – 서버가 클라이언트에서 실행시킬 수 있는 로직을 전송하여 클라이언트의 기능을 확장시킬 수 있다. 이를 통해 클라이언트가 사전에 구현해야하는 기능의 수를 줄여 간소화시킬 수 있다.

참고문서 : What is REST

RESTful API Naming

URI(Uniform Resource Identifier) Uniform: 리소스 식별하는 통일된 방식 Resource: 자원, URI로 식별할 수 있는 모든 것(제한 없음) Identifier: 다른 항목과 구분하는데 필요한 정보

URI는 Resource(or Representation)만 식별함

ex) 미네랄을 캐라 -> 미네랄이 리소스, 회원을 등록하고 수정하는 기능 -> 회원이라는 개념 자체가 리소스

최근에는 Resource 대신 Representation 라는 표현을 사용하기 시작함

하지만 아직 Resource라는 표현을 쓰는 비중이 많으니 이 글에서는 Resource와 Representation를 함께 표기하겠다.

1. 리소스를 표현하기 위해 명사를 사용하라

RESTful URI이 가르키는 resource(or representation)는 수행되는 행위가 아니라 객체다.

이 resource (or representation)를 네 가지 범주로 나누어보겠다.

항상 리소스가 어느 범주에 해당하는 지 확인하고, 그 범주에 맞는 네이밍 컨벤션을 일관되게 사용하라.

문서(Document)

단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)

단수 사용 (/device-management, /user-management) http://api.example.com/device-management/managed-devices/{device-id} http://api.example.com/user-management/users/{id} http://api.example.com/user-management/users/admin

컬렉션(Collection)

서버가 관리하는 리소스 디렉터리

서버가 리소스의 URI를 생성하고 관리

복수를 사용하라

POST 기반 등록

예) 회원 관리 API

복수 사용 (/users)

http://api.example.com/user-management/users http://api.example.com/user-management/users/{id}

스토어(Store)

클라이언트가 관리하는 자원 저장소

클라이언트가 리소스의 URI를 알고 관리

PUT 기반 등록

예) 정적 컨텐츠 관리, 원격 파일 관리

복수 사용 (/files) http://api.example.com/files http://api.example.com/files/new_file.txt

컨트롤 URI 혹은 컨트롤러(Controller)

문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행

동사를 직접 사용

예) GET, POST만 사용할 수 있는 HTTP FORM의 경우 컨트롤 URI(동사로 된 리소스 경로)를 사용 ex) /members/delete, /members/new 등

동사 사용 (/checkout, /play 등) http://api.example.com/cart-management/users/{id}/cart/checkout http://api.example.com/song-management/users/{id}/playlist/play

2. 일관성이 핵심이다

일관된 resource (or representation) naming conventions과 URI 형식을 사용하면 모호함이 최소화되고 가독성과 지속성이 극대화된다. 일관성을 위해 다음과 같은 디자인 힌트를 구현할 수 있다.

– 계층 관계 표현을 위해 `/`를 사용하라

http://api.example.com/device-management http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices/{id} http://api.example.com/device-management/managed-devices/{id}/scripts http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

– 마지막 문자로 `/` 를 사용하지 마라

http://api.example.com/device-management/managed-devices/ /* X */ http://api.example.com/device-management/managed-devices /* O */

– 가독성을 위해 `-`(하이픈)을 사용하라

//More readable http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //Less readable http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation

– `_` (언더스코어)는 사용하지 마라

일부 브라우저나 화면에서는 `_` (언더스코어)는 가려질 수 있기 때문에 혼란을 피하기 위해 `-` (하이픈)를 사용한다

//More readable http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More error prone http://api.example.com/inventory_management/managed_entities/{id}/install_script_location

– 소문자를 사용하라

Schem과 HOST에만 대소문자 구별이 없고, 이 외에는 대소문자가 구별된다.

아래 3개의 URL는 대소문자 구별이 없다면 모두 동일한 URL지만, 1번과 2번은 동일하고 3번은 같지 않다.

http://api.example.org/my-folder/my-doc //1 HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2 http://api.example.org/My-Folder/my-doc //3

– 파일 확장자를 사용하지 마라

가독성에 좋지 않고 어떤 장점도 있지 않다.

// X http://api.example.com/device-management/managed-devices.xml // O http://api.example.com/device-management/managed-devices

3. CRUD 함수명을 사용하지 마라

URI는 어떤 동작이 수행되는 지 가르키는 게 아니라, 리소스를 가르키는 것이다.

리소스에 대한 작업은 HTTP Method를 이용하도록 한다.

HTTP GET http://api.example.com/device-management/managed-devices //Get all devices HTTP POST http://api.example.com/device-management/managed-devices //Create new Device HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id

4. 필터를 위해 쿼리 파라미터를 사용해라

Resource(or Reperesentation)에 대한 정렬, 필터링, 페이징은 신규 API를 생성하지 않고 쿼리 파라미터를 활용해라.

http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices?region=USA http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

참고문서 : REST Resource Naming Guide

[REST API] URL 규칙, RESTful한 URL이란?

728×90

REST API URL 규칙, RESTful한 URL이란?RESTful API

REST API 설계시 가장 중요한 항목은 아래 두가지이다.

1️⃣ URI는 정보의 자원을 표현해야 한다는 점

2️⃣ 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다는 점

두 가지를 기억하며, 좀 더 RESTful한 URL을 설계해보자!(REST API에 대해 더 알아보려면? 👉 클릭 )

1. 소문자를 사용한다.

주소에서 대소문자를 구분하므로, 카멜방식이 아닌 소문자를 사용하여 작성한다.

Bad

http://restapi.example.com/users/postComments

Good

http://restapi.example.com/users/post-comments

2. 언더바를 대신 하이픈을 사용한다.

가급적 하이픈의 사용도 최소화하며, 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에 사용한다.

Bad

http://restapi.example.com/users/post_comments

Good

http://restapi.example.com/users/post-comments

3. 마지막에 슬래시를 포함하지 않는다.

슬래시는 계층을 구분하는 것으로, 마지막에는 사용하지 않는다.

Bad

http://restapi.example.com/users/

Good

http://restapi.example.com/users

4. 행위는 포함하지 않는다.

행위는 URL대신 Method를 사용하여 전달한다.(GET, POST, PUT, DELETE 등)

Bad

POST http://restapi.example.com/users/1/delete-post/1

Good

DELETE http://restapi.example.com/users/1/posts/1

5.파일 확장자는 URI에 포함시키지 않는다.

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않습니다. Accept header를 사용하도록 한다.

Bad

http://restapi.example.com/users/photo.jpg

Good

GET http://restapi.example.com/users/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

6. 가급적 전달하고자하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

Bad

http://restapi.example.com/posts/duplicating

Good

http://restapi.example.com/posts/duplicate

728×90

REST API 설계 (네이밍)

728×90

반응형

필자는 현재 Open API 서비스를 개발/운영을 담당하고 있다. 신규 API URL을 네이밍 할 때마다 정체성의 혼란이 오는것을 느낀다. 이번 기회에 RESTful한 API 네이밍 방법을 정리하여 필자의 전두엽에 평안을 주기위해 이 글을 작성한다.

📌 목차

1. REST란?

2. Resource 표현방식

3. REST API 설계

4. REST API Sample

1. REST란?

Representational State Transfer의 약자이며, 다음과 같이 구성되어 있다.

자원(Resource): URI

행위(Verb): HTTP Method

표현(Representations)

즉 REST는 URI를 통해 자원(Resource)을 표시하고, HTTP Method를 기반으로 해당 자원의 행위를 규정하여 그 결과를 받는 것을 말한다.

HTTP Method는 크게 GET, POST, PUT, DELETE가 대표적이며, 일반적으로 CRUD(Create, Read, Update, Delete)에서 조회는 GET, 등록은 POST, 수정은 PUT, 삭제는 DELETE를 이용한다.

* Resource의 여러가지 형태

1. Resource는 단건일 수 있고, 단건의 집합일 수 있다.

– 손님: /customer

– 손님들 : /customers

– 2번 ID를 가진 손님 : /customers/2

2. Resource는 서브Resource를 포함할 수 있다.

손님들의 계좌를 관리한다면, 손님의 하위에 계좌를 포함할 수 있다.

– 2번 손님의 모든 계좌 : /customers/2/accounts

– 2번 손님의 2번 계좌 : /cusotmers/2/accounts/2

2. Resource 표현방식

Resource는 표현방식에 따라 document, collection, store, controller 4가지로 나눌수 있다.

2.1 Document

Document는 1개의 개체를 나타내는 것으로 객체 인스턴스, DB의 record와 유사한 개념을 갖는다.

REST에서는 리소스 집합(collection)중 하나로 표현되어지며 일반적으로 collection의 뒤에 ‘/’를 통해 구분한다.

http://api.example.com/device-management/managed-devices/{device-id} http://api.example.com/user-management/users/{id} http://api.example.com/user-management/users/admin

2.2 Collection

Collection은 단일 Resource(document)들의 묶음을 의미한다. 복수형 단어를 사용한다.

http://api.example.com/device-management/managed-devices http://api.example.com/user-management/users http://api.example.com/user-management/users/{id}/accounts

2.3 Store

새로운 URI를 생성하지 않으며, 처음에 resource를 등록할 때 client가 전달한 key를 이용한다. 복수형 단어를 사용한다.

http://api.example.com/cart-management/users/{id}/carts http://api.example.com/song-management/users/{id}/playlists

2.4 Contoller

Controller Resource Model은 절차 컨셉을 모델로 한다. Controller Resource는 Client에서 서버의 실행 가능한 function을 의미하는것과 같다.

Controller resources are like executable functions, with parameters and return values; inputs, and outputs.

Use “verb” to denote controller archetype.

RESTFUL 네이밍 가이드(https://restfulapi.net/resource-naming)에서는 Controller의 경우 resource를 조작하는것이 아닌 직접 function을 실행하는 행위를 나타내기위해 사용하므로, 동사를 사용해도 무방하다고 설명한다.

http://api.example.com/cart-management/users/{id}/cart/checkout http://api.example.com/song-management/users/{id}/playlist/play

3. REST API 설계

3.1 동사가 아닌 명사로 Resource를 표현하자

RESTful URI는 동사가 아니라 명사 구성하는 것을 추천한다. 이유는 명사는 해당 Resource의 속성을 표현할 수 있지만 동사는 그렇지 못하기때문이다.

http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices/{device-id} http://api.example.com/user-management/users/ http://api.example.com/user-management/users/{id}

3.2 소문자를 사용한다.

주소에서 대소문자를 구분하므로, 카멜방식이 아닌 소문자를 사용하여 작성한다.

// Bad http://restapi.example.com/users/postComments // Good http://restapi.example.com/users/post-comments

* 카멜표기법:

이른바 낙타표기법은 말그대로 낙타의 등모습을 닮았다.

카멜표기법은 기본적으로 변수명을 모두 소문자로 쓴다.

다만 여러 단어가 이어지는 경우 첫단어를 제외하고 각 단어의 첫글자만 대문자로 지정해 주는 방식이다.

integer type의 변수를 예시로 보면,

int myFirstVariable;

방금 선언한 변수는 세단어로 되어있다. my, first, variable

모두 소문자로 작성하되, 첫단어를 제외한 각 단어의 첫글자를 대문자로 사용한다.

즉 my를 제외한 first와 variable의 첫단어만을 바꿔주는 표기법!

3.3 언더바(_)를 대신 하이픈(-)을 사용한다.

가급적 하이픈(-)의 사용도 최소화하며, 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에 사용한다.

// Bad http://restapi.example.com/users/post_comments // Good http://restapi.example.com/users/post-comments

3.4 마지막에 슬래시를 포함하지 않는다.

슬래시는 계층을 구분하는 것으로, 마지막에는 사용하지 않는다.

// Bad http://restapi.example.com/users/ // Good http://restapi.example.com/users

3.5 행위는 포함하지 않는다.

행위는 URL에 포함하지않고, HTTP Method를 사용하여 전달한다. (GET, POST, PUT, DELETE 등)

// Bad POST http://restapi.example.com/users/1/delete-post/1 // Good DELETE http://restapi.example.com/users/1/posts/1

3.6 파일 확장자는 URI에 포함시키지 않는다.

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. Accept Header를 사용하도록 한다.

// Bad http://restapi.example.com/users/photo.jpg // Good GET http://restapi.example.com/users/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

3.7 가급적 전달하고자하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

// Bad http://restapi.example.com/posts/duplicating // Good http://restapi.example.com/posts/duplicate

4. REST API Sample

카카오 기업의 OPEN API를 사례로 REST API Sample URL을 몇가지 소개한다.

* 카카오 REST API 레퍼런스: https://developers.kakao.com/docs/latest/ko/reference/rest-api-reference

URL Method 기능 /oauth/authorize GET 인가 코드 받기 /oauth/token POST 토큰 받기, 토큰 갱신하기 /v1/api/talk/profile GET 프로필 가져오기 /v2/api/talk/memo/default/send POST 나에게 기본 템플릿으로 메시지 보내기 /v1/api/story/post/note POST 글 스토리 쓰기 /v1/api/story/delete/mystory DELETE 내 스토리 삭제하기 /v1/payment/approve POST 단건 결제 승인 /v1/payment/cancel POST 결제 취소 /v1/payment/order POST 주문 조회 /v1/payment/manage/subscription/status POST 정기 결제 상태 조회

참조

https://restfulapi.net/resource-naming/

https://developers.kakao.com/

P.S. SOAP과 REST 비교: https://server-engineer.tistory.com/737

REST API 규칙

IBM® UrbanCode Release REST API는 안정적인 상호작용을 위해 규칙 세트를 준수합니다.

REST URL 서버의 각 요소 유형은 복수 양식을 사용하는 최상위 레벨 URL로 표시됩니다. 일반적으로 URL에서는 카멜 케이스 규칙으로 형식화된 UCR 사용자 인터페이스에서 사용하는 용어를 사용합니다. 예를 들어, 변경 유형은 URL http:// base_url /changeTypes/ 에 환경 변수는 URL http:// base_url /environmentReservations/ 에 애플리케이션은 URL http:// base_url /applications/ 에 표시될 수 있으며 여기서 base_url 은 서버에 대한 호스트 이름과 경로입니다.

필수 HTTP 헤더 REST API의 대부분의 조작은 JSON 형식의 입력을 허용하거나 JSON 형식으로 출력을 리턴합니다(또는 모두 지원함). HTTP 규칙에 따라 매체 유형 값 application/json 을 사용하며 JSON 입력을 제공하는 조작에는 Content-Type 요청 헤더가 필요하고 JSON 출력을 생성하는 조작에는 Accept 요청 헤더가 필요합니다. 개발자의 편의를 위해서 매체 유형이 text/html 이고 조회 매개변수 json 이 임의의 값으로 요청 URL에 추가된 경우, 목록 및 개별 항목(아래에 표시됨)의 GET 메소드에서도 JSON 출력을 생성합니다. 이 매개변수는 Accept 헤더를 수정하는 특수 도구 없이 웹 브라우저에서 JSON 출력을 렌더링하는 데 유용합니다. 예를 들어, 모든 애플리케이션에 대한 JSON 출력을 표시하려면 웹 브라우저의 위치 표시줄에 http:// base_url /applications/?json 을 입력합니다.

id 특성 애플리케이션과 같은 요소에는 고유 ID(UUID) 특성이 있으며 이 특성은 JSON 오브젝트 표시에서 JSON 문자열과 같은 id 특성으로 표시됩니다. 해당 UUID를 사용하여 특정 요소를 참조할 수 있습니다. 이 UUID를 REST API 조작의 URL 위치나 요소의 JSON 표시 내에 사용할 수 있습니다.

기본 조작 기본 작성, 읽기, 업데이트, 삭제 조작은 공통 REST API 규칙에 따라 제공됩니다. 요소 유형의 최상위 레벨 URL은 해당 유형의 항목 콜렉션을 나타냅니다. 해당 유형의 모든 요소 목록을 JSON 오브젝트 배열로 렌더링하려면 HTTP 메소드 GET을 적절한 HTTP 헤더나 json 조회 매개변수와 함께 사용하십시오. 새 요소를 작성하려면 HTTP 메소드 POST를 적절한 유형의 최상위 레벨 URL에 사용하고 요청 본문에 요소의 JSON 데이터를 제공하십시오. 응답 본문에는 서버에서 생성한 id 특성과 함께 새 요소의 전체 JSON 표시가 포함됩니다. JSON 오브젝트의 배열을 제공하여 단일 요청에 여러 요소를 작성할 수도 있습니다. 이 경우, 응답 본문에 새 요소의 JSON 배열이 요청에 제공된 순서대로 포함되어 있습니다. 마찬가지로 요소의 JSON 배열이 있는 HTTP PUT 메소드를 사용하여 여러 요소의 데이터를 업데이트할 수도 있습니다. 전체 JSON 요소나 요소의 UUID만 포함된 JSON 배열이 있는 HTTP DELETE 메소드를 사용하여 여러 요소를 삭제할 수 있습니다. 기존 단일 요소에서 조작을 실행하려면 해당 요소의 UUID를 해당 유형의 최상위 레벨 URL에 추가하십시오. 예를 들어, 제공된 샘플 릴리스의 JSON 데이터에 액세스하려면 URL http:// base_url /releases/00000000-0000-0000-0000-000000000036/ 과 함께 HTTP 메소드 GET을 사용하십시오. 요소의 데이터를 업데이트하려면 HTTP PUT 메소드를 사용하고 요청 본문에 업데이트된 JSON 오브젝트를 제공하십시오. (이 경우, 요청 URL의 UUID를 요청 본문의 id 특성보다 우선해서 사용합니다.) 요소를 삭제하려면 HTTP DELETE 메소드를 사용하십시오. 이 경우 요청 본문이 필요하지 않습니다.

출력 형식 작성, 읽기 및 업데이트 조작(POST, GET, PUT)을 사용하는 경우, 선택적 format 조회 매개변수를 포함하여 특정 유스 케이스에 맞게 JSON 출력을 조정할 수 있습니다. 이 매개변수를 제공하지 않거나 매개변수 값을 인식할 수 없는 경우, 기본 형식을 사용합니다. 각 요소 유형은 다른 형식 세트를 지원합니다. 이러한 형식은 요소 유형의 참조 정보와 함께 나열됩니다. 일부 형식에서는 세부사항이 길게 표시되고 일부 형식은 짧게 표시될 수 있지만 표시되는 정보만 다른 것이며 값은 같습니다. list 및 detail 형식은 모든 요소 유형과 함께 사용할 수 있습니다. list 형식에서는 요약 정보(예: 항목 표에 표시되는 내용)를 제공합니다. detail 형식에서는 더 자세한 정보를 제공합니다. 이 형식에는 관련 요소 컨텐츠가 포함되는 경우가 많습니다. 일부 요소의 경우 이러한 형식이 동일합니다. 또한 name 특성이 있는 요소 유형은 name 형식도 있습니다. 이 형식에는 id 및 name 특성만 포함되는데 이 특성은 선택할 항목을 이름별 목록으로 표시하는 데 유용합니다. 간단하게 name 을 유형의 최상위 레벨 URL에 추가해서 요소 유형의 name 형식을 생성할 수도 있습니다. 예: GET http:// base_url /applications/name .

JSON 입력 규칙 JSON 데이터를 작성 또는 업데이트 조작의 입력으로 제공하는 경우 REST API에서는 요소에 작성할 수 있는 특성만 고려합니다. API에서 기타 모든 데이터를 무시합니다. 읽기 전용 특성(예: 계산된 개수 또는 작성 날짜)은 업데이트되지 않습니다. API에서 인식되지 않는 특성을 무시합니다. 참조를 설정하는 데 사용한 id 특성을 제외한 관련 요소 특성도 업데이트되지 않습니다. { “name”: “New Release”, “team”: { “id”: “00000000-0000-0000-0000-000000000206”, “name”: “Not the actual Team name” }, “lifecycleModel”: “00000000-0000-0000-0000-000000000006”, “totalChanges”: 42, “BadProperty”: “xxxx” } 예를 들어, 다음 JSON 입력을 제공하여 릴리스를 작성한다고 가정해 보십시오. BadProperty 및 계산된 값 totalChanges 는 무시합니다. 이 경우 위 입력은 다음과 같은 더 간단한 입력이 됩니다. { “name”: “New Release”, “team”: “00000000-0000-0000-0000-000000000206”, “lifecycleModel”: “00000000-0000-0000-0000-000000000006” } API에서는 이 입력을 처리할 때 릴리스 작성에 필요한 특성만 인식합니다. 따라서 인식되지 않는 특성인및 계산된 값는 무시합니다. 이 경우 위 입력은 다음과 같은 더 간단한 입력이 됩니다. 마찬가지로 기존 요소를 업데이트할 때 API에서는 JSON 입력에 지정하는 특성만 변경합니다. API에서는 생략하는 특성을 변경하지 않습니다. 특성 값을 지우려면 해당 특성에 대해 명시적 JSON 널 값을 지정하십시오. { “id”: “00000000-0000-0000-0000-123456789000”, “name”: “New Feature”, “description”: “”, “status”: “In Progress”, “type”: { “id”:”00000000-0000-1201-0000-000000000001″, “name”:”Feature”, “icon”:”feature”} } 다음 입력은 변경사항을 샘플 릴리스와 연관시키지만 변경사항의 다른 특성은 업데이트하지 않습니다. { “id”: “00000000-0000-0000-0000-123456789000”, “release”: “00000000-0000-0000-0000-000000000036” } 이 조작을 되돌리고 이 변경사항에서 샘플 릴리스로의 연관을 지우려는 경우 다음 입력을 사용할 수 있습니다. { “id”: “00000000-0000-0000-0000-123456789000”, “release”: null } 예를 들어, 다음 컨텐츠가 있는 기존 변경이 있다고 가정하십시오.다음 입력은 변경사항을 샘플 릴리스와 연관시키지만 변경사항의 다른 특성은 업데이트하지 않습니다.이 조작을 되돌리고 이 변경사항에서 샘플 릴리스로의 연관을 지우려는 경우 다음 입력을 사용할 수 있습니다.

참조 id 특성이 포함된 JSON 오브젝트를 사용하여 단일 요소를 참조할 수 있습니다. 위 설명과 같이 참조된 요소의 다른 특성은 무시됩니다. 예를 들어, 다음 JSON 오브젝트 전체는 변경사항을 릴리스와 연관시키는 경우와 같습니다. { “id”: “00000000-0000-0000-0000-123456789000”, “release”: “00000000-0000-0000-0000-000000000036” } { “id”: “00000000-0000-0000-0000-123456789000”, “release”: {“id”:”00000000-0000-0000-0000-000000000036″} } { “id”: “00000000-0000-0000-0000-123456789000”, “release”: { “id”:”00000000-0000-0000-0000-000000000036″, “name”:”Sample Release”} } { “id”: “00000000-0000-0000-0000-123456789000”, “release”: { “id”:”00000000-0000-0000-0000-000000000036″, “name”:”Not the actual Release name”} } 일반적으로 요소의 UUID가 포함된 JSON 문자열이나 같은 값이 있는특성이 포함된 JSON 오브젝트를 사용하여 단일 요소를 참조할 수 있습니다. 위 설명과 같이 참조된 요소의 다른 특성은 무시됩니다. 예를 들어, 다음 JSON 오브젝트 전체는 변경사항을 릴리스와 연관시키는 경우와 같습니다.

다중 값(콜렉션) 참조 applications 특성에 제공하는 값은 영향을 주지 않습니다. 대신 다른 URL을 사용하여 릴리스에서 애플리케이션을 추가하거나 제거합니다. 릴리스와 연관된 애플리케이션 나열: GET /releases/{releaseID}/applications

릴리스에 애플리케이션 추가: POST /releases/{releaseID}/applications/{applicationID}

릴리스에서 애플리케이션 제거: DELETE /releases/{releaseID}/applications/{applicationID} 일부 관계에는 다중 값을 포함할 수 있습니다. 예를 들어, 단일 릴리스를 여러 애플리케이션에 연관시킬 수 있습니다. 관계의 단일 값 측면을 작성하거나 업데이트하는 경우와 같은 일부 상황에서는 이러한 관계가 업데이트되지 않습니다. 예를 들어, 릴리스를 작성할 때특성에 제공하는 값은 영향을 주지 않습니다. 대신 다른 URL을 사용하여 릴리스에서 애플리케이션을 추가하거나 제거합니다. 그러나 다른 경우에는(특히, 요소에 특정 관계가 필요한 경우), 관계의 단일 값 측면에 대한 입력을 지정할 수 있습니다. 예를 들어, 애플리케이션을 여러 팀에 연관시킬 수 있습니다. 이 경우, 애플리케이션을 작성할 때 “teams” 특성에 대한 UUID 문자열의 JSON 배열을 제공할 수 있습니다. 이 관계를 조작할 수 있는 특수 URL은 없습니다.

키-값 특성 일부 요소 유형은 정적으로 정의된 특성과 함께 자유 양식 키-값 쌍을 스토리지에 저장하여 검색할 수 있는 기능을 지원합니다. 이 특성 유형은 통합 제공자로 링크된 데이터를 나타내는 경우가 많습니다. 예를 들어, IBM Rational® Team Concert 작업 항목을 나타내는 변경사항에서 작업 항목의 ID를 이 키-값 스토리지의 특성으로 저장할 수 있습니다. properties 특성의 관련 요소로 표시됩니다. 예를 들어, 다음 코드는 이름이 first , second , third 인 키-값 특성의 변경을 보여줍니다. { “id”: “00000000-0000-0000-0000-123456789000”, “name”: “New Feature”, “description”: “”, “status”: “In Progress”, “type”: { “id”:”00000000-0000-1201-0000-000000000001″, “name”:”Feature”, “icon”:”feature”}, “properties”: { “first”:”first value”, “second”:”second value”, “third”:”third value”} } 키와 값 모두 JSON 문자열로 표시되어야 합니다. 정적으로 정의된 특성과 같이 입력에서 키가 생략되면 업데이트 조작에서도 변경하지 않습니다. 키-값 쌍을 지우려면 JSON 널값을 키에 지정하십시오. 키-값 특성은 JSON 데이터에서특성의 관련 요소로 표시됩니다. 예를 들어, 다음 코드는 이름이인 키-값 특성의 변경을 보여줍니다.키와 값 모두 JSON 문자열로 표시되어야 합니다. 정적으로 정의된 특성과 같이 입력에서 키가 생략되면 업데이트 조작에서도 변경하지 않습니다. 키-값 쌍을 지우려면 JSON 널값을 키에 지정하십시오.

페이지 매기기 일부 요소 유형에서는 최상위 레벨 GET 요청에서 전체 목록 대신 요소의 서브세트를 제공할 수 있습니다. 이러한 요소 서브세트를 검색하는 경우 각 요청에서 데이터의 단일 “페이지”만 로드하기 때문에 이러한 조작을 “페이지 매기기”라고 합니다. 페이징을 대체하는 두 가지 양식이 있는데 이 양식에서는 조회 매개변수나 HTTP Range 헤더를 사용합니다. 페이지 매기기에 조회 매개변수를 사용하려면 HTTP GET 요청에 rowsPerPage 및 pageNumber 조회 매개변수를 모두 지정하십시오. 첫 번째 페이지를 검색하려면 코드 pageNumber=1 을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 요청 GET http:// base_url /applications/?rowsPerPage=5&pageNumber=1 을 사용하십시오. Range 헤더를 사용하려면 항목 범위의 시작 및 종료 값을 지정하여 영(0) 기반 포함 값을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 다음 헤더를 요청 GET http:// base_url /applications/ 에 추가하십시오. Range: items=0-4 HTTP헤더를 사용하려면 항목 범위의 시작 및 종료 값을 지정하여 영(0) 기반 포함 값을 지정하십시오. 예를 들어, 처음 다섯 개 애플리케이션을 검색하려면 다음 헤더를 요청에 추가하십시오. Content-Range 헤더를 사용하여 검색되는 실제 범위와 사용 가능한 총 항목 수를 지정합니다. 예를 들어, 열 개 목록 중에 처음 다섯 개의 변경사항을 요청하는 경우 응답에 다음 헤더가 포함됩니다. Content-Range: 0-4/10 처음 다섯 개 변경사항을 요청하고 있지만 세 개의 변경사항만 있는 경우, 헤더가 다음과 같이 표시됩니다. Content-Range: 0-2/3 페이지 매기기 요청 방법에 관계 없이 HTTP 응답에서는헤더를 사용하여 검색되는 실제 범위와 사용 가능한 총 항목 수를 지정합니다. 예를 들어, 열 개 목록 중에 처음 다섯 개의 변경사항을 요청하는 경우 응답에 다음 헤더가 포함됩니다.처음 다섯 개 변경사항을 요청하고 있지만 세 개의 변경사항만 있는 경우, 헤더가 다음과 같이 표시됩니다.

정렬 최상위 레벨 GET 오퍼레이션의 결과를 정렬하려면 orderField 및 sortType 매개변수를 지정하십시오. orderField 매개변수에는 정렬에 사용할 단일 특성 이름이 포함되어야 합니다. sortType 매개변수에는 오름차순으로 정렬하는 값 asc 또는 내림차순으로 정렬하는 값 desc 가 포함되어야 합니다. 관련 요소의 특성을 정렬하려면 특성 이름을 마침표로 구분된 경로 형식으로 지정하십시오. 예를 들어, 연관 릴리스에 따라 변경사항 목록을 정렬하려면 값 release.name 을 지정하십시오. 이 경로의 특성 중 하나가 널이면 순서가 지정되지 않습니다. format 매개변수와 결합할 수 있습니다. 예를 들어 detail 형식으로 처음 다섯 개의 변경사항을 관련 릴리스 이름에 따라 오름차순으로 정렬하여 검색하려면 다음 요청을 사용하십시오. GET http:// base_url /changes/?format=detail&rowsPerPage=5& pageNumber=1&orderField=release.name&sortType=asc 일부 특성은 정렬에 사용할 수 없습니다. 특히 요약 데이터를 나타내는 특성(예: 항목 개수)은 일반적으로 정렬에 사용할 수 없습니다. 정렬을 페이지 매기기 및매개변수와 결합할 수 있습니다. 예를 들어형식으로 처음 다섯 개의 변경사항을 관련 릴리스 이름에 따라 오름차순으로 정렬하여 검색하려면 다음 요청을 사용하십시오.일부 특성은 정렬에 사용할 수 없습니다. 특히 요약 데이터를 나타내는 특성(예: 항목 개수)은 일반적으로 정렬에 사용할 수 없습니다.

RESTful API 설계 규칙

프로젝트를 하면서 API를 설계할때 늘상 헷갈리는 것이 Rest API입니다. 한번 정리해두고 늘 참고합시다.

Representational State Transfer (REST) refers to a group of software architecture design constraints that bring about efficient, reliable, and scalable distributed systems.

– MDN의 REST

REST란 Representational State Transfer의 약자로, MDN에 따르면 효과적이고 신뢰를 주고 측정가능한 분산시스템을 위한 소프트웨어 설계 제약 사항입니다. 즉, 자원을 정의하고 그 주소를 지정하는 전반의 방법을 말하는 것입니다.

REST의 기본 개념은 상태와 관계가 잘 정의되고 표준화한 포맷으로 document같은 리소스를 전송하는 것입니다. 이 방식을 잘 적용한 설계를 RESTful 이라고 합니다.

1. REST API 기본규칙

URI는 정보의 자원을 표현해야 한다. resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다. resource의 스토어 이름으로는 복수 명사를 사용해야 한다. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다. HTTP Method나 동사표현이 URI에 들어가면 안됩니다. :id 와 같이 변하는 값은 하나의 특정 resource를 나타내는 고유값이어야 합니다.

흔히 하는 실수는 URI에 자원에 대한 행위를 넣는 것입니다.

// 잘못된 사례 GET /chatrooms/get/:id POST /chatrooms/create GET /chatrooms/delete/:id POST /chatrooms/update/:id

위 잘못된 사례는 아래와 같이 고칠 수 있습니다.

// 올바른 사례 GET /chatrooms/:id POST /chatrooms DELETE /chatrooms/:id PUT /chatrooms/:id

HTTP Method

주로 쓰는 Method GET : 조회 (받겠다) POST : 리소스 생성 (보내겠다) PUT : 리소스 전체 갱신(놓겠다/넣겠다) PATCH : 리소스 부분 갱신(붙이겠다) DELETE : 리소스 삭제 (지정한 서버의 파일을 삭제하겠다)

나머지 Method HEAD: GET과 유사하나 HTTP 메시지 헤더만 반송하고 데이터 내용을 돌려보내지 않음(헤더만 보겠다) OPTION: 통신 옵션을 통지/조사 TRACE: 리퀘스트 라인과 헤더를 그대로 클라이언트에 반송(리퀘스트 치환상태를 조사할 때 사용) CONNECT: 암호화된 메시지를 프록시로 전송

설계 예시 CRUD HTTP URI 전체 리소스 조회 GET /resources 특정 리소스 조회 GET /resources/:id 리소스 생성 POST /resources 리소스 전체 수정 PUT /resources/:id 리소스 일부 수정 PATCH /resources/:id 특정 리소스 삭제 DELETE /resources/:id

2. Rest API 세부규칙

슬래시(/)는 계층 관계를 나타냅니다.

http://www.example.com/fruits/banana

URI의 마지막엔 슬래시(/)를 포함하지 않습니다.

http://www.example.com/fruits/banana/ (X)

가독성을 높이기 위해 하이픈(-)을 사용할 수 있으나 언더바(_)를 사용하진 않는다.

http://www.example.com/tropical_fruits/banana/ (X) http://www.example.com/tropical-fruits/banana/ (O)

URI 경로에는 소문자를 씁니다.

http://api.example.restapi.org/my-folder/my-doc HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc 위의 두 URI는 같은 URI입니다. 호스트에서는 대소문자를 구별하지 않기 때문이지요. http://api.example.restapi.org/my-folder/my-doc http://api.example.restapi.org/My-Folder/my-doc 하지만 위의 두 URI는 다른 URI입니다. 뒤에 붙는 path가 대소문자로 구분되기 때문입니다.

RFC 3986에 따르면 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다고 합니다. 따라서 전부 소문자이거나 전부 대문자이면 괜찮지만, 일반적으로 대문자는 잘 쓰지 않기 때문에 소문자로 쓰는 것을 권합니다.

예시출처: RESTful API를 설계하기 위한 디자인 팁(https://spoqa.github.io/2013/06/11/more-restful-interface.html)

파일 확장자는 URI에 포함하지 않고 Accept header을 사용합니다 리소스간 연관관계가 있는 경우

/리소스명/리소스ID/관계있는 다른 리소스명(일반적으로 소유has의 관계) GET /users/:id/skills

참고문헌

REST API URI의 7가지 규칙

REST API URI의 규칙에 대해 알아보기 전에 용어에 대해 간략히 짚고 넘어가도록 하겠습니다.

URI

REST API는 URL를 사용합니다. 오늘날의 웹에서 URI 디자인은 API의 리소스 모델을 명확하게 전달하는 걸작부터 사람들이 이해하기 힘들어하는 것까지 다양합니다.

팀버너스 리는 “웹 아키텍처의 원칙”이라는 목록에 URI의 불투명성에 대한 메모를 기재하였습니다.

“식별자를 사용할 수 있는 유일한 것은 객체를 참조하는 것입니다. 역참조하지 않을 때는 다른 정보를 얻으려면 URI 문자열의 내용을 참조하십시오.”

클라이언트는 웹의 연결 패러다임을 따라야 하고 URI를 불완전한 식별자로 취급해야 합니다.

REST API 디자이너는 REST AP의 리소스 모델을 잠재적 클라이언트 개발자에게 전달하는 URI를 만들어야 합니다.

이번 포스팅에서는 REST API URI의 몇 가지 디자인 규칙을 소개하고자 합니다.

규칙에 대해 알아보기 전에 이 섹션에서 제시하는 규칙에 따라 URI 형식에 대한 단어는 URI 형식과 관련이 있습니다. RFC 3986은 아래와 같이 일반 URI 구문을 정의하였습니다.

URI = scheme “://” authority “/” path [ “?” query ] [ “#” fragment ]

규칙 1

후행 슬래시(/)는 URI에 포함되지 않아야 한다

이것은 URI 경로를 결정하는 마지막 문자로써 반드시 따라야 하는 아주 중요한 규칙 중 하나입니다. 슬래시는 의미가 전혀 없을 뿐만 아니라 혼동을 일으킬 수 있습니다. REST API에서는 클라이언트 개발자에게 넘어가는 API URL에 후행 슬래시가 포함되지 않아야 합니다.

많은 웹 컴포넌트나 프레임워크들은 다음의 두 URI를 동일하게 취급합니다.

http://moretranslate.co.kr/moretranslate

http://moretranslate.co.kr/moretranslate/

그러나 URI에 있는 모든 문자들은 리소스의 고유 ID에 포함됩니다.

2개의 다른 URI는 다른 2개의 리소스에 매핑됩니다. URI가 다르면 리소스도 달라집니다. 그래서 REST API는 깨끗하고 명확한 URI를 생성하고 전달해야 합니다. 또한 클라이언트가 부정확하게 접근하려는 시도들을 모두 용납하지 않아야 합니다.

우리의 개발 파트너인 클라이언트만이 API 호출 대상이 아니기 때문입니다.

규칙 2

계층 관계를 나타낼 때 슬래시 구분자(/)를 사용해야 한다

슬래시 문자는 URI의 경로 부분에서 리소스 간의 계층적 관계를 나타내기 위해서 사용합니다.

예 : http://board.com/board/52 -> 게시판의 52번 글.

규칙 3

URI의 가독성을 높이기 위해서 하이픈(-) 문자를 사용한다

당신이 정의한 URI가 사람들에게 더 쉽게 읽힐 수 있도록 하이픈 문자를 사용하십시오. 영어로 공백이나 하이픈을 사용하는 모든 곳에서 URI에 하이픈을 사용해야 합니다.

URI를 사람들이 쉽게 스캔하고 해석할 수 있도록 하이픈(-) 문자를 사용하여 긴 경로 세그먼트에서 이름의 가독성을 향상시키십시오. 영어로 공백이나 하이픈을 사용하는 모든 곳에서 URI에 하이픈을 사용해야 합니다.

예 : http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

규칙 4

언더바(_) 문자는 URI에 사용하지 않는다

텍스트 뷰어 프로그램(브라우저, 편집기 등)은 클릭할 수 있다는 것을 표현하기 위해 종종 URI에 밑줄을 칩니다. 프로그램의 글꼴에 따라 언더바(_) 문자가 이러한 밑줄로 인해 부분적으로 가려지거나 완전히 숨겨질 수 있습니다.

이러한 혼란을 방지하려면 밑줄(_) 대신 하이픈(-) 문자를 사용하시는 것이 좋습니다.

규칙 5

URI를 작성하는 데에는 소문자가 적합하다

대문자로 인해 때로 문제가 발생하는 경우가 있기 때문에 URI를 작성할 때는 소문자를 사용하는 것이 좋습니다. RFC 3986은 체계와 호스트 구성 요소를 제외하고 URI를 대소문자를 구분하여 정의합니다. 대문자로 인해 문제가 발생할 수 있으므로 편리한 경우 URI 경로에 소문자를 사용하는 것이 좋습니다.

예 :

1) http://api.example.com/my-folder/my-doc

2) HTTP://API.EXAMPLE.COM/my-folder/my-doc

위의 URI는 괜찮습니다. URI 형식 사양(RFC 3986)은 이 URI를 URI #1과 동일한 것으로 간주합니다.

3) http://api.example.com/My-Folder/my-doc

이 URI는 URI 1 및 2와 동일하지 않으므로 불필요한 혼동을 일으킬 수 있습니다.

규칙 6

파일 확장자는 URI에 포함하지 않는다

웹상에서 점(.)은 URI의 파일명과 확장자를 구분하는 데 사용됩니다. REST API는 메시지 엔티티 바디의 본문 형식을 나타내기 위해 이러한 파일 확장자를 URI에 포함해서는 안 됩니다. 대신 Content-Type이라는 헤더를 통해 전달되는대로 미디어 유형을 사용하여 본문의 콘텐츠를 처리하는 방법을 결정해야 합니다.

http://api.college.com/students/3248234/courses/2005/fall.json

http://api.college.com/students/3248234/courses/2005/fall

형식 표현하기 위해 파일 확장자를 사용해서는 안 됩니다.

REST API 클라이언트는 HTTP에서 제공하는 형식 선택 매커니즘인 Accept 요청 헤더를 사용하도록 권장합니다.

간단한 링크와 디버깅이 가능하게 하기 위해, REST API는 쿼리 스트링 매개변수를 통해 미디어 유형 선택을 지원할 수 있습니다.

규칙 7

보통 URI는 영어로 작성되는데 작성되는 영어는 단수여야 하는가? 복수여야 하는가?

여기에는 단순 유지 규칙이 적용됩니다. 단일 인스턴스를 복수형으로 표시하는 게 잘못되었다고 생각할 수도 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있습니다. 여기에는 단순 유지 규칙이 적용됩니다. 내부 문법학자는 복수형을 사용하여 리소스의 단일 인스턴스를 설명하는 것이 잘못되었다고 말할 것이지만 실용적인 대답은 URI 형식을 일관되게 유지하고 항상 복수형을 사용하는 것입니다.

이상한 복수형(person/people과 같은)을 다루지 않아도 API 소비자가 편하게 사용하고 API 제공 업체가 구현하기가 더 쉽습니다.(대부분의 최신 프레임워크가 /students(복수형) 및 /students/232324(복수형 중 특정하기) 형태로 처리됨

그런데 관계는 어떻게 다룰까요? 관계가 다른 리소스 내에서만 존재할 수 있는 경우 RESTFUL 원칙은 유용한 지침을 제공합니다. 예를 들어, 한 학생에게 여러 코스가습니다. 이러한 과정은 다음과 같이 /students 에 매핑됩니다.

http://api.college.com/students/3248234/courses ID가 3248234인 학생이 학습한 모든 과정 목록을 검색한다

http://api.college.com/students/3248234/courses/physics ID가 3248234인 학생을 위한 과정 물리학을 검색한다.

결론

REST API 서비스를 디자인할 때, URI로 정의되는 리소스의 주의를 많이 기울여야 합니다.

서비스의 각 리소스들은 최소 하나의 URI로 식별될 것입니다. 특정 URI가 리소스를 적절하게 설명할 때 가장 좋습니다. URI는 이해 가능성과 사용성을 향상시키기 위해 예측 가능해야 하고, 계층 구조적이어야 합니다. 즉, 일관성이 있다는 관점에서 예측 가능하고, 데이터가 구조를 갖추고 있다는 점에서 계층적이다는 것입니다.

RESTFul API는 소비자를 위해 작성되었습니다. URI의 이름과 구조는 해당 소비자에게 의미를 전달할 수 있어야 합니다. 위의 규칙을 따르면 훨씬 더 행복한 클라이언트로 훨씬 깨끗한 REST API를 만들 수 있습니다. 이것은 반드시 지켜야 하는 제약 조건은 아닙니다. 다만 여러분이 위의 규칙들을 준수해 봄으로써 API를 향상시킬 수 있을 것입니다.

* 본문 내용은 https://dzone.com/articles/7-rules-for-rest-api-uri-design-1 를 각색한 자료입니다.

7 Rules for REST API URI Design – DZone Integration

URIs, or Uniform Resource Identifiers, should be designed to be readable and clearly communicate the API resource model. These rules will help you succeed.

dzone.com

RESTful API의 URL 작성 규칙

REST API란?

REST(Representational State Transfer)는 HTTP 네트워크 상의 리소스(Resource, 자원)를 정의하고 해당 리소스를 URI라는 고유의 주소로 접근하는 접근 방식을 의미하며, REST API란 REST 방식을 통해서 리소스에 접근하기 위한 서비스 API를 지칭합니다.

REST에서 의미하는 리소스란?

REST에서 의미하는 자원은 데이터베이스에 저장된 데이터, 문서, 이미지, 동영상 등 HTTP 통신을 통해 주고 받을 수 있는 모든 것을 의미합니다.

URI(Uniform Resource Identifier)와 URL(Uniform Resource Locator)

URI는 네트워크 상에 있는 특정 리소스를 식별하는 통합 자원 식별자(Uniform Resource Identifier)를 의미합니다.

URL은 인터넷에 있는 리소스를 나타내는 통합 리소스 식별자를 의미하며, 우리가 흔히들 이야기하는 웹 상의 주소를 의미합니다.

URI는 URL의 상위 개념으로 볼 수 있습니다.

URI는 리소스를 식별하는 식별자 역할을 하고, URL은 리소스의 위치를 가리킵니다.

예) http://www.itivllage.tistory.com/manage? id = 1

위 예에서 ‘http://www.itivllage.tistory.com/manage’까지는 리소스의 위치를 가리키는 URL이라고 할 수 있고, ‘http://www.itivllage.tistory.com/manage? id = 1’는 리소스를 식별하기 위한 ‘id = 1’이라는 고유 식별자 붙었으므로 URI라고 할 수 있습니다.

REST API URI 작성 규칙

그러면 이번에는 HTTP 상에서 REST API 서비스를 만드는 입장에서 REST API URI를 작성하는 규칙들을 살펴보도록 하겠습니다.

URI 작성 기본 규칙

URI의 마지막이 ‘/’로 끝나지 않아야 합니다. better http://www.itivllage.tistory.com/coffees (ㅇ) worse http://www.itivllage.tistory.com/coffees/ (x)

동사 보다는 명사를 사용합니다. better http://www.itivllage.tistory.com/coffees (ㅇ) worse http://www.itivllage.tistory.com/coffees/update (x)

단수형 보다는 복수형 명사를 사용합니다. better http://www.itivllage.tistory.com/coffees (ㅇ) worse http://www.itivllage.tistory.com/coffees (x)

URI는 기본 소문자로 사용합니다.

언더스코어( _ ) 대신에 하이픈(-)을 사용합니다.

파일 확장자는 URI에 포함하지 않습니다.

URI에서 리소스 간의 관계를 표현하는 방법

REST API를 작성하다보면 특정 리소스 간의 관계를 URI로 표현해야 할 경우가 굉장히 많습니다.

이해를 위해 예시를 살펴보도록 하겠습니다.

‘http://www.itivllage.tistory.com/members’는 전체 회원에 대한 리소스를 의미합니다.

‘http://www.itivllage.tistory.com/members/1’는 1이라는 ID를 가지는 회원에 대한 리소스를 의미합니다..

‘ http://www.itivllage.tistory.com/members/1/orders’는 1이라는 ID를 가지는 회원의 주문에 대한 리소스를 의미합니다.

더 읽을 거리

RESTful API 의미와 설계 규칙

반응형

1. RESTful API란?

REST란 REpresentational State Trasfer의 약어로 웹을 이용할 때 제약 조건들을 정의하는 소프트웨어 아키텍처 스타일입니다. HTTP URL을 통해 자원(Resource)을 명시하고 HTTP Method(GET, POST, PUT, DELETE)를 통해서 해당 자원(URL)에 대한 CRUD(Create, Read, Update, Delete)를 적용하는 것을 의미합니다. 한마디로 HTTP의 장점을 살리고자 하는 통신 규약이라 할 수 있습니다. 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개되었으며 RESTful API는 이러한 규약을 바탕으로 리소스 중심으로 설계하고 기능에 맞게 HTTP Method 사용하여 설계된 API입니다.

GET : 지정된 URL에서 리소스의 표현을 조회

POST : 지정된 URL에 신규 리소스를 생성

PUT : 지정된 URL에 리소스를 생성하거나 업데이트

PATCH : 리소스의 부분 업데이트

DELETE : 지정된 URL의 리소스를 제거

2. REST 특징

인터페이스 일관성 : 일관적인 인터페이스로 분리되어야 합니다.

무상태 : 각 요청 간 클라이언트의 context, 세션과 같은 상태 정보를 서버에 저장하지 않습니다.

캐시 처리 가능 : 클라이언트는 응답을 캐싱할 수 있어야 합니다. 캐시를 통해 대량의 요청을 효율적으로 처리할 수 있습니다.

계층화 : 클라이언트는 대상 서버에 직접 연결되어있는지, Proxy를 통해서 연결되었는지 알 수 없습니다.

Code on demand : 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트를 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있습니다.

클라이언트/서버 구조 : 아키텍처를 단순화시키고 작은 단위로 분리함으로써 클라이언트-서버의 각 파트가 독립적으로 구분하고 서로 간의 의존성을 줄입니다.

3. REST 구성요소

REST는 다음과 같은 3가지로 구성되어 있습니다.

자원(Resource) : HTTP URL 자원에 대한 행위 : HTTP Method 자원에 대한 표현(Representations)

4. REST API 설계 Rulse 및 예시

1. 소문자를 사용한다.

❌ http://cocoon1787.tistory.com/users/Post-Comments

⭕ http://cocoon1787.tistory.com/users/post-comments

대문자는 때로 문제를 일으키는 경우가 있기 때문에 소문자로 작성합니다.

2. 언더바( _ ) 대신 하이픈( – )을 사용한다.

❌ http://cocoon1787.tistory.com/users/post_comments

⭕ http://cocoon1787.tistory.com/users/post-comments

정확한 의미나 단어 결합이 불가피한 경우 하이픈(“-“)을 사용하며 하이픈(“-“) 사용도 최소한으로 설계합니다.

언더바(“_”)는 사용하지 않습니다.

3. 마지막에 슬래시를 포함하지 않는다.

❌ http://cocoon1787.tistory.com/users/

⭕ http://cocoon1787.tistory.com/users

슬래시(“/”)는 계층 관계를 나타낼 때 사용됩니다.

4. 행위를 포함하지 않는다.

❌ POST http://cocoon1787.tistory.com/users/post/1

⭕ DELETE http://cocoon1787.tistory.com/users/1

자원에 대한 행위는 HTTP Method로 표현합니다.(GET, POST, DELETE, PUT)

5. 파일 확장자는 URL에 포함시키지 않는다.

❌ http://cocoon1787.tistory.com/users/photo.jpg

⭕ GET http://cocoon1787.tistory.com/users/photo HTTP/1.1 Host: cocoon1787.tistory.com Accept: image/jpg

URL에 메시지 body 내용의 포맷을 나타내기 위한 파일 확장자를 적지 않습니다. 대신 Accept header를 사용합니다.

6. 자원에는 형용사, 동사가 아닌 명사를 사용하며, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.

❌ http://cocoon1787.tistory.com/duplicating

⭕ http://cocoon1787.tistory.com/duplicate

URL은 자원을 표현하는데 중점을 두기 때문에 동사, 형용사보다는 명사를 사용하여야 합니다.

HTTP 응답 코드

cocoon1787.tistory.com/514?category=925946

참고 URL

반응형

RESTful API 설계 가이드

1. RESTful API 설계 가이드 본 문서는 REST API를 좀 더 RESTful 하게 설계하도록 가이드할 목적으로 만들어졌다. 따라서, 기본적인 REST API 개념 설명은 아래의 링크로 대신한다.

REST API 제대로 알고 사용하기

REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁 일부 규칙들은 기존에 존재하는 회사 규칙 때문에 보편적인 REST API의 철학과 다를 수 있다.

RESTful API 설계 가이드 심화 과정 REST API 관점에서 바라보는 HTTP 상태 코드(HTTP status code) TOC

1. RESTful API 설계 가이드

2. URL Rules 2.1. 마지막에 / 포함하지 않는다. 2.2. _(underbar) 대신 -(dash)를 사용한다. 2.3. 소문자를 사용한다. 2.4. 행위(method)는 URL에 포함하지 않는다. 2.5. 컨트롤 자원을 의미하는 URL 예외적으로 동사를 허용한다.

3. Set HTTP Headers 3.1. Content-Location 3.2. Content-Type 3.3. Retry-After 3.3.1. Case 1. 인증 3.3.2. Case 2. 자원 요청 3.4. Link

4. Use HTTP methods 4.1. POST, GET, PUT, DELETE 4가지 methods는 반드시 제공한다. 4.2. OPTIONS, HEAD, PATCH를 사용하여 완성도 높은 API를 만든다. 4.2.1. OPTIONS 4.2.2. HEAD 4.2.3. PATCH 4.2.3.1. Example

5. Use HTTP status 5.1. 의미에 맞는 HTTP status를 리턴한다 5.2. HTTP status만으로 상태 에러를 나타낸다

6. Use the correct HTTP status code. 6.1. 성공 응답은 2XX 로 응답한다. 6.2. 실패 응답은 4XX 로 응답한다. 6.3. 5XX 에러는 절대 사용자에게 나타내지 마라!

7. Use HATEOAS 7.1. 구성 요소 7.2. 응답 예제

8. Paging, Ordering, Filtering, Field-Selecting 8.1. Paging 8.1.1. Paging Key 8.1.2. 응답 예제 8.1.2.1. HTTP Header의 Link 속성을 이용한다. 8.1.2.2. HATEOAS로 응답한다. 8.1.2.3. Link, HATEOAS 모두 사용한다. 8.2. Ordering 8.2.1. 요청 샘플 8.3. Filtering 8.4. Field-Selecting 8.4.1. 요청 샘플

9. Versioning 9.1. 종류 9.1.1. 예외적으로 서비스의 기본 도메인이 3차인 경우 path level 에 모두 명시한다. 9.2. URI Versioning 개발 가이드

2. URL Rules

2.1. 마지막에 / 포함하지 않는다. Bad

http: // api.test.com /users/ Good

http:

2.2. _(underbar) 대신 -(dash)를 사용한다. -(dash)의 사용도 최소한으로 설계한다. 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우 반드시 -(dash) 사용한다. Bad

http: // api.test.com /users/ post_commnets Good

http: // api.test.com /users/ post-commnets

2.3. 소문자를 사용한다. Bad

http: // api.test.com /users/ postCommnets Good

http: // api.test.com /users/ post-commnets

2.4. 행위(method)는 URL에 포함하지 않는다. Bad

POST http: // api.test.com /users/ 1 /delete-post/ 1 Good

DELETE http: // api.test.com /users/ 1 /posts/ 1

2.5. 컨트롤 자원을 의미하는 URL 예외적으로 동사를 허용한다. 함수처럼, 컨트롤 리소스를 나타내는 URL은 동작을 포함하는 이름을 짓는다. Bad

http: // api.test.com /posts/ duplicating Good

http: // api.test.com /posts/ duplicate

3. Set HTTP Headers

3.1. Content-Location POST 요청은 대부분 idempotent(멱등, f(f(x))=f(x) ) 하지 않다. (멱등, 반환되는 응답 리소스의 결과가 항상 동일하다) Location and Content-Location are different. Location indicates the URL of a redirect, while Content-Location indicates the direct URL to use to access the resource, without further content negotiation in the future.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Location

POST / users { “name” : “hak” } 위와 같은 요청은 매번 다른 리소스를 반환한다.

첫 번째는 /users/1 두 번째는 /users/2 … n번째는 /users/n 따라서 요청의 응답 헤더에 새로 생성된 리소스를 식별할 수 있는 Content-Location 속성을 이용한다.

HTTP/1.1 200 OK Content-Location : /users/1 GET, PUT 등의 요청은 idempotent 하다 GET /users/1 의 경우 언제나 같은 결과로 응답한다. PUT을 POST처럼 쓰는 경우엔 idempotent하지 않을 수 있다. HATEOAS로 Content-Location 를 대체할 수 있다.

3.2. Content-Type application/json을 우선(될 수 있다면 이것만!)으로 제공한다. 2018년이다. json을 이용하자. application/xml 등을 제공해서 응답 포맷을 이원화하지 말자! 응답 포맷을 여러 개로 나누면 요청 포맷도 나눠야 한다.

3.3. Retry-After 비정상적인 방법(DoS, Brute-force attack)으로 API 서버를 이용하려는 경우 429 Too Many Requests 오류 응답과 함께 일정 시간 뒤 요청할 것을 나타낸다.

HTTP/1.1 429 Too Many Requests Retry-After : 3600

3.3.1. Case 1. 인증 /auth OAuth, JWT 같은 인증 관련 리소스를 요청하는 작업

/login Id, Password를 이용한 로그인 작업 비정상적인 요청(401) 일 때 두 가지 응답 방안 n 시간 동안 n 회만 요청 가능 429 응답과 함께 Retry-After: n n 회만 요청 가능 401 응답과 함께 해당 사용자(IP)는 더 이상 인증 관련 API를 사용할 수 없고 다시 요청하려면 특수한 절차가 필요하다는 메세지 응답 Retry-After 와 관계없음

3.3.2. Case 2. 자원 요청 /posts 특정 사용자가 의도적으로 서버 과부화를 목적으로 반복 요청하는 경우 n 시간 동안 n 회 이상 요청한 경우 429

3.4. Link 페이징 처리를 위해 사용한다. github 방법을 따른다. https://developer.github.com/v3/#pagination

HTTP/1.1 200 OK Link : ; rel=”next”, < https://api.test.com/users?page=50&per_page=100>; rel=”last” rel Name Description next The link relation for the immediate next page of results. last The link relation for the last page of results. first The link relation for the first page of results. prev The link relation for the immediate previous page of results. query parameter의 page , per_page 이름은 알맞게 변경한다.

4. Use HTTP methods

4.1. POST, GET, PUT, DELETE 4가지 methods는 반드시 제공한다. methods POST GET PUT DELETE /users 사용자 추가 사용자 전체 조회 사용자 추가 or 사용자 수정 사용자 전체 삭제 /users/hak 405 ERROR 사용자 ‘hak’ 조회 사용자 ‘hak’ 수정 사용자 ‘hak’ 삭제 PUT /users 경우 표에선 사용자 추가 or 사용자 수정으로 했지만, 보통 Collection 에 PUT 요청은 지원하지 않으므로 405 ERROR 응답하기도 한다. Collection: /users/hak 에서 users , 집합 Document: /users/hak 에서 hak , 집합에 속한 자원

4.2. OPTIONS, HEAD, PATCH를 사용하여 완성도 높은 API를 만든다.

4.2.1. OPTIONS https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS 현재 End-point가 제공 가능한 API method를 응답한다.

OPTIONS /users/ hak

HTTP/1.1 200 OK Allow : GET,PUT,DELETE,OPTIONS,HEAD

4.2.2. HEAD https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/HEAD 요청에 대한 Header 정보만 응답한다. body가 없다.

HEAD /users

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

4.2.3. PATCH https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH PUT 대신 PATCH method를 사용한다. 자원의 일부를 수정할 때는 PATCH 가 목적에 맞는 method다. PATCH , which is used to apply partial modifications to a resource.

PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload

4.2.3.1. Example id name level 1 hak 10 2 lee 5 PUT 요청 시 요청을 일부분만 보낸 경우 나머지는 default 값으로 수정되는 게 원칙이다. 그러나, 대부분 PUT 요청에서 이와 같이 개발하진 않는다.

PUT /users/ 1 { “level” : 11 }

HTTP/1.1 200 OK { ” name” : null, ” level” : 11 } PUT은 다음과 같이 바뀌지 않는 속성도 보내야 한다.

PUT /users/ 1 { “name” : “hak” “level” : 11 }

HTTP/1.1 200 OK { ” name” : “hak”, ” level” : 11 } PATCH를 이용하여 원래의 목적대로 ‘level’만 변경하는 요청을 보낸다.

PATCH /users/ 1 { “level” : 11 }

HTTP/1.1 200 OK { ” name” : “hak”, ” level” : 11 }

5. Use HTTP status 좀 더 자세한 내용은 다음 글에서 설명한다. REST API 관점에서 바라보는 HTTP 상태 코드(HTTP status code)

5.1. 의미에 맞는 HTTP status를 리턴한다 Bad

HTTP/1.1 200 OK { ” result” : false ” status” : 400 } status는 200 으로 성공인데 body 내용엔 실패에 관한 내용을 리턴하고 있다. 모든 응답을 200 으로 처리하고 body 내용으로 성공|실패 를 판단하는 구조에서 사용된다. 잘못된 설계다.

Good

HTTP/1.1 400 Bad Request { ” msg” : “check your parameter” }

5.2. HTTP status만으로 상태 에러를 나타낸다 세부 에러 사항은 응답 객체에 표시하거나, 해당 에러를 확인할 수 있는 link를 표시한다. http 상태 코드를 응답 객체에 중복으로 표시할 필요 없다. Bad

HTTP/1.1 404 Not Found { ” code” : 404, ” error_code” : -765 } Good

HTTP/1.1 404 Not Found { ” code” : -765, ” more_info” : “https://api.test.com/errors/-765″ }

6. Use the correct HTTP status code. 좀 더 자세한 내용은 다음 글에서 설명한다. REST API 관점에서 바라보는 HTTP 상태 코드(HTTP status code)

6.1. 성공 응답은 2XX 로 응답한다. 200 : [OK]

201 : [Created] 200과 달리 요청에 성공하고 새로운 리소스를 만든 경우에 응답한다. POST, PUT에 사용한다.

202 : [Accepted] 클라이언트 요청을 받은 후, 요청은 유효하나 서버가 아직 처리하지 않은 경우에 응답한다. 비동기 작업 요청에 대한 응답이 일정 시간 후 완료되는 작업의 경우 작업 완료 후 클라이언트에 알릴 수 있는 server push 작업을 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URL을 응답해야 한다. HTTP/1.1 202 Accepted { ” links” : [ { ” rel” : “self”, ” method” : “GET”, ” href” : “https://api.test.com/v1/users/3” } ] }

204 : [No Content] 응답 body가 필요 없는 자원 삭제 요청(DELETE) 같은 경우 응답한다. 200 응답 후 body에 null , {} , [] , false 로 응답하는 것과 다르다. 204의 경우 HTTP body가 아예 없는 경우

6.2. 실패 응답은 4XX 로 응답한다. 400 : [Bad Request] 클라이언트 요청이 미리 정의된 파라미터 요구사항을 위반한 경우 파라미터의 위치( path , query , body ), 사용자 입력 값, 에러 이유 등을 반드시 알린다 case 1 { “message” : “‘ name ‘( body ) must be Number, input ‘name ‘: test123 ” } case 2 { “errors” : [ { “location” : “body” , “param” : “name” , “value” : “test123” , “msg” : “must be Number” } ] }

401 : [Unauthorized]

403 : [Forbidden] 해당 요청은 유효하나 서버 작업 중 접근이 허용되지 않은 자원을 조회하려는 경우 접근 권한이 전체가 아닌 일부만 허용되어 요청자의 접근이 불가한 자원에 접근 시도한 경우 응답한다.

404 : [Not Found]

405 : [Method Not Allowed] 405 code는 404 code와 혼동될 수 있기 때문에 룰을 잘 정하고 시작한다. POST /users/1 의 경우 404로 응답한다고 생각할 수 있지만, 경우에 따라 405 로 응답할 수 있다.

/users/:id URL은 GET, PATCH, DELETE method는 허용되고 POST는 불가한 URL이다. 만약 id가 1 인 사용자가 없는 경우엔 404로 응답하지만(GET, PATCH, DELETE의 경우), POST /users/1 는 /users/:id URL이 POST method를 제공하지 않기 때문에 405로 응답하는 게 옳다. Allow: GET, PATCH, DELETE HTTP header에 허용 가능한 method를 표시한다.

409 : [Conflict] 해당 요청의 처리가 비지니스 로직상 불가능하거나 모순이 생긴 경우 e.g.) DELETE /users/hak 의 경우, 비지니스 로직상 사용자의 모든 자원이 비어있을 때만 사용자를 삭제할 수 있는 규칙이 있을 때 409로 응답한다. 409 Conflict { “message” : “first, delete connected resources.” “links” : [ { “rel” : “posts.delete” , “method” : “DELETE” , “href” : “https://api.test.com/v1/users/hak/posts” }, { “rel” : “comments.delete” , “method” : “DELETE” , “href” : “https://api.test.com/v1/users/hak/comments” } ] }

429 : [Too Many Requests] Retry-After: 3600 (HTTP Headers) DoS, Brute-force attack 같은 비정상적인 접근을 막기 위해 요청의 수를 제한한다.

6.3. 5XX 에러는 절대 사용자에게 나타내지 마라! API Server level에선 500 에러가 나선 안된다.

이건 서비스 장애! 즉, API Server는 모든 발생 가능한 에러를 핸들링해야 한다. 만약 API Server를 서빙하는 웹서버(apache, nginx)가 오류일 때는 500 가능

7. Use HATEOAS Hypermedia as the Engine of Application State A hypermedia-driven site provides information to navigate the site’s REST interfaces dynamically by including hypermedia links with the responses.

https://spring.io/understanding/HATEOAS REST API는 요청-응답 이라는 간단한 구조로 이루어져 있다.

또한 응답의 내용도 단순하다. 만약, POST /users {“name”: “hak”} 이라는 요청을 보내면

서버는 응답으로 201 Created {“id”: 1, “name”:”hak”} 와 같이 응답할 것이다. 여기서 문제는 이 응답만으론 사용자 리스소의 상태가 전이되기엔 정보가 부족하다는 것이다. REST API가 아닌 HTML 환경에선 눈에 보이는 화면이 있기 때문에 POST /users 후에 사용자의 상태가 전이될 수 있는 link를 화면에서 제공할 수 있다. 이 문제를 해결하기 위해 응답 객체에 해당 리소스의 상태가 전이될 수 있는 link들을 함께 제공한다. link들을 통해 리소스의 다음 상태 전이 정보를 동적으로 제공한다.

7.1. 구성 요소 변경될 리소스의 상태 관계 rel self : 현재 URL 자신, 예약어처럼 쓰임

요청 URL href

요청 Method method

…(그 외 추가사항)

{ “rel” : “self” , “href” : “http://api.test.com/users/1” , “method” : “GET” }

7.2. 응답 예제

201 Created { “id” : 1 , “name” : “hak” , “createdAt” : “2018-07-04 14:00:00” “links” : [ { “rel” : “self” , “href” : “http://api.test.com/users/1” , “method” : “GET” }, { “rel” : “delete” , “href” : “http://api.test.com/users/1” , “method” : “DELETE” }, { “rel” : “update” , “href” : “http://api.test.com/users/1” , “method” : “PATCH” , “more_info” : “http://api.test.com/docs/user-update” “body” : { “name” : “{The value to be modified}” } }, { “rel” : “user.posts” , “href” : “http://api.test.com/users/1/posts” , “method” : “GET” } ] } rel 의 값은 self 를 제외하고 내부 규칙을 정해서 따른다.

의미만 정확히 드러나면 된다.

more_info , body 와 같이 내부 정의된 key를 사용해도 된다. more_info : 해당 link의 세부 정보를 알고 싶은 경우 탐색할 웹 페이지 주소 body : 해당 link가 POST , PUT 인 경우 파라미터를 body에 넣어 보내기 때문에 보낼 수 있는 body 파라미터 샘플. 파라미터가 너무 많거나 제약사항이 엄격한 경우 more_info 로 해당 link의 상세 정보를 확인할 수 있게 한다.

8. Paging, Ordering, Filtering, Field-Selecting

8.1. Paging Collection(리스트)에 대한 GET 요청의 경우( GET /users ) 한 번에 모든 결과를 응답하지 않고 적당한 크기로 데이터 셋을 나눠서 응답한다.

8.1.1. Paging Key Github page per_page

Atlassian start limit

Digitalocean page per_page

개발자 관점 offset limit

어떤 key로 paging을 처리할지 변경될 수 있으니 개발자는 코드의 설정 값으로 언제든 key 이름을 변경할 수 있게 구현한다.

8.1.2. 응답 예제

GET /users

8.1.2.1. HTTP Header의 Link 속성을 이용한다.

HTTP/1.1 200 OK Link : < https://api.test.com/users?offset=10&limit=10>; rel=”next”, ; rel=”last”, ; rel=”first”, ; rel=”prev”, [ {1, …}, {2, …}, … {10,…}, ]

8.1.2.2. HATEOAS로 응답한다.

HTTP/1.1 200 OK [ { 1, …}, {2, …}, … {10,…}, “links” : [ { ” rel” : “next”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=10&limit=10 }, { ” rel” : “last”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=50&limit=10 }, { ” rel” : “first”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=0&limit=10 }, { ” rel” : “prev”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=0&limit=0 }, ] ]

8.1.2.3. Link, HATEOAS 모두 사용한다.

HTTP/1.1 200 OK Link : < https://api.test.com/users?offset=10&limit=10>; rel=”next”, ; rel=”last”, ; rel=”first”, ; rel=”prev”, [ {1, …}, {2, …}, … {10,…}, “links” : [ { ” rel” : “next”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=10&limit=10 }, { ” rel” : “last”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=50&limit=10 }, { ” rel” : “first”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=0&limit=10 }, { ” rel” : “prev”, ” method” : “GET”, ” link” : “https://api.test.com/users?offset=0&limit=0 }, ] ]

8.2. Ordering Collection(리스트)에 대한 GET 요청의 경우( GET /users ) 리스트를 클라이언트의 요청에 맞게 정렬해 응답한다. order 라는 key를 사용한다. 오름차순: key

내림차순: -key

8.2.1. 요청 샘플

GET /users? order =name ?order=-name : name 내림차순 name desc

?order=-name,level : name 내림차순, level 오름차순 name desc, level asc

8.3. Filtering Collection(리스트)에 대한 GET 요청의 경우( GET /users ) 리스트 검색 조건을 요청할 수 있다. AND , OR

= , !=

> , >=

< , >=

IN (OR), NOT IN

LIKE (include) type = ssd or (cpu=1 or memory>=2) and staus != 04

8.4. Field-Selecting Collection(리스트)에 대한 GET 요청의 경우( GET /users ) 리스트 결과의 일부분만 선택해서 응답받을 수 있다.

8.4.1. 요청 샘플

GET /users?fields = level

HTTP/1.1 200 OK { ” level” : 10 } include: ?fields=id,name id, name 만 반환 HTTP/1.1 200 OK { ” id” : 1, ” name” : “hak” }

exclude: ?-fields=level level 제외 모두 반환 http

HTTP/1.1 200 OK

{

“id”: 1,

“name”: “hak”,

“createdAt”: “2018-07-04 14:00:00″

}

존재하지 않는 key fields 에 존재하는 key가 하나도 없는 경우, fields 모두 무시 (?fields=aaaaaa 혹은 ?fields=aaaaaa,bbbb) HTTP/1.1 200 OK { ” id” : 1, ” name” : “hak”, ” level” 10, “createdAt” : “2018-07-04 14:00:00″ } fields 에 key가 일부분만 존재하는 경우, 존재하는 key로만 selecting (?fields=aaaaaa,name) HTTP/1.1 200 OK { ” name” : “hak” }

9. Versioning

9.1. 종류 URI Versioning http: http:

Accept header Accept: application /vnd.example.v1+json Accept: application /vnd.example+json; version = 1.0 URI Versioning을 채택하고, 버저닝 정보는 host레벨이 아닌 path레벨에 명시한다. Do

http: Don’t

http:

9.1.1. 예외적으로 서비스의 기본 도메인이 3차인 경우 path level 에 모두 명시한다. Domain

http: http: http: Your Service API URI

http: Allow

http: // service3.test.com /api/ v1 Don’t http://api.service3.test.com/v1

9.2. URI Versioning 개발 가이드 개발 코드에서 버저닝 정보를 관리하지 않는다.

개발 프로젝트 폴더의 버저닝은 VCS(e.g. git)를 이용한다.

v1(v1 branch), v2(master branch)

웹 서버의 reverse-proxy 기능을 활용한다 웹 APP 서버의 라우팅은 버저닝을 제외하고 개발한다. /users, /posts http://api.test.com/v1 -> (reverse-proxy) -> 웹 APP / 시나리오 case (Node.js express server) v1 process app-name: v1 port: 3001 dir: /home/v1 Apache ProxyPassReverse “/v1” “http://127.0.0.1:3001” Nginx location /v1 {proxy_pass http://127.0.0.1:3001} v2 process app-name: v2 port: 3002 dir: /home/v2 Apache ProxyPassReverse “/v2” “http://127.0.0.1:3002” Nginx location /v2 {proxy_pass http://127.0.0.1:3002} API 버저닝 여부에 관계없이 프로젝트 구조가 변경되지 않는다.

Bad

– routes – /v1 – /users – /posts – /v2 – /users – /posts – … Good

– routes – /users – /posts

키워드에 대한 정보 rest api 규칙

다음은 Bing에서 rest api 규칙 주제에 대한 검색 결과입니다. 필요한 경우 더 읽을 수 있습니다.

이 기사는 인터넷의 다양한 출처에서 편집되었습니다. 이 기사가 유용했기를 바랍니다. 이 기사가 유용하다고 생각되면 공유하십시오. 매우 감사합니다!

사람들이 주제에 대해 자주 검색하는 키워드 [API]3. REST API개념, 구성요소, URL설계규칙, REST Client, API사용 실습

• REST API
• URL
• 구성요소
• Insomnia
• Rest Client
• Google Books
• 카카오
• 알라딘
• YTS
• developer console

[API]3. #REST #API개념, #구성요소, #URL설계규칙, #REST #Client, #API사용 #실습

---

YouTube에서 rest api 규칙 주제의 다른 동영상 보기

주제에 대한 기사를 시청해 주셔서 감사합니다 [API]3. REST API개념, 구성요소, URL설계규칙, REST Client, API사용 실습 | rest api 규칙, 이 기사가 유용하다고 생각되면 공유하십시오, 매우 감사합니다.