[network] API 란? 개념 이해하기 - rest api 1편

개발 공부를 하다 보면 조금씩 API라는 용어를 접하게 되는데 API라는 것이 참 다양한 부분에서 사용되기에 처음에 API를 이해하는데 많은 어려움이 있었고 rest api를 정리하기 전 API의 대한 개요를 먼저 잡고 진행을 하는 것이 좋을 것 같다는 생각을 하게 되어 포스팅을 시작하려고 한다. 

수정이 필요한 내용의 피드백은 언제든지 환영 입니다.

 

1. API란

API란 "Application Programing Interface"의 약자로, 컴퓨터나 컴퓨터 프로그램 사이의 연결을 의미하며 일종의 소프트웨어 인터페이스로 다른 종류의 소프트웨어에 대한 서비스를 제공한다. 

• 인터페이스 : 서로 다른 두 개의 시스템 혹은 장치 간의 신호를 주고받기 위한 접점으로 사용자가 기기를 쉽게 동작시키는데 도움을 주는 소프트웨어 시스템을 의미한다.

위의 설명에서 주목해야 하는 부분은 컴퓨터 혹은 컴퓨터 프로그램 사이의 연결인데 웹 개발을 하는 개발자 입장에서는 우리의 시스템이 서드 파티 시스템의 기능을 이용하기 위해서 (예 : 결재 시스템) 해당 API를 사용하는 경우가 있으며 응용 프로그램 개발자의 경우 OS의 기능을 사용하기 위해 OS에서 제공하는 API를 이용하게 된다. 

자주 헷갈려하는 부분은 API라는 용어가 웹에서 서버 간의 통신을 위해서만 사용된다는 부분으로 그렇지 않다는 것을 이야기하고자 한다.

표현식은 다르지만 결국 API가 갖는 의미는 컴퓨터 프로그램 사이의 연결 혹은 컴퓨터 간의 연결을 의미하기 때문에 표현식은 달라도 용어는 중복이 될 수 있다는 것이다.
OS가 제공해 주는 API를 사용하고자 하는 경우 보통은 C, C++ 언어를 이용하여 개발을 하게 되는데 OS(운영체제)가  C언어로 개발이 되어 있기 때문이다.

 

---

2. API 디자인 가이드

WEB 개발자로 API를 만들기 위해서 우리가 지켜야 할 규칙을 설명하고 마무리하고자 한다.

• 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다. ex) http://localhost/search
• URI 마지막 문자로(/)는 포함하지 않는다. ex) http://localhost/search/ <- 옳지 않음
• 하이픈(-)은 URI 가독성을 높이는 데 사용한다. ex) http://localhost/search/info-detail
• 밑줄(_)은 사용하지 않는다. ex) http://localhost/info_detail
• URI 경로에는 소문자가 적합하다.
• 파일 확장자는 URI에 포함하지 않는다. ex) http://localhost/user-information.jsp
• 프로그래밍 언어에 의존적인 확장자를 사용하지 않는다. ex) http://localhost/info-detail.do
• 구현에 의존적인 경로를 사용하지 않는다. ex) http://localhost/servlet/classes/java
• 세션 ID를 포함하지 않는다. ex) http://localhost/info?sesstion-id=123234523
• 프로그래밍 언어의 Method 명을 이용하지 않는다 ex) http://localhost/search/info?action=read
• 명사에 단수형 보다는 복수형을 사용해야 한다. 컬렉션에 대한 표현은 복수로 사용한다. ex) http://localhost/classes/examples/user-info
• 컨트롤러 이름으로는 동사나 동사구를 사용한다. ex) http://localhost/user/search
• 경로 부분 중 변하는 부분은 유일한 값으로 대체한다. (여기서 유일한 값은 식별 값을 의미한다.)
  • ex)  http://localhost/user/1
  • ex) http://localhost/user/{user-id}
• CRUD 기능을 나타내는 것은 URI에 사용하지 않는다. ex)  http://localhost/user/read
• URI Query Parameter 디자인 URI 쿼리 부분으로 컬렉션 결과에 대해서 필터링할 수 있다.
• URI 쿼리는 컬렉션의 결과를 페이지로 구분하여 나타내는 데 사용한다.
• API에 있어서 서브 도메인은 일관성 있게 사용해야 한다. ex) https://api.google.com/
• ex) https://api-google.com/
• ex) https://google.com/
• 클라이언트 개발자 포탈 서브 도메인은 일관성 있게 만든다.
• ex) http://dev-google.com/

 

---

REST API 6가지 제약조건 : https://gorilla-ohgiraffers.tistory.com/3

[REST API] Roy Fielding이 말하는 6가지 제약 조건