[Api] Open API 디자인

API 란?

운영체제, 시스템, 애플리케이션, 라이브러리 등을 개발자들이 프로그래밍 작업을 통해 응용 프로그램을 작성할 수 있는 다양한 인터페이스들을 총칭한다. (예: Window API, Java API, HTML5 API, Android API…)

오픈 API 란?

API 중에서 플랫폼의 기능 또는 컨텐츠를 외부에서 쓸 수 있도록 웹 프로토콜(HTTP)로 호출할 수 있도록 개방(open)한 API를 의미한다. 네이버 개발자센터에서 제공하고 있는 지도, 검색을 비롯 기계번역, 캡차, 단축 URL 등 대부분 API 들은 HTTP로 호출할 수 있는 오픈 API에 해당한다.

네이버와 카카오 API 확인하기

NAVER Open API(https://developers.naver.com 참조)

이전(2015년 쯤)에는 네이버에서 제공하는 API를 사용하기 위해 'API 키'라는 유니크한 텍스트 문자열을 발급받고, 이를 API 호출시 같이 API 게이트웨이 서버로 전송함으로써 인증된 사용자임을 입증했다. 새로운 개발자센터에서는 API 키 방식은 더 이상 사용하지 않고 애플리케이션마다 일종의 유니크한 아이디와 비밀번호(클라이언트 아이디, 시크릿)값을 이용해서 인증하고 있다.

https://openapi.naver.com/버전/서비스구분/API 구분 형태
예시) 기계번역 API : https://openapi.naver.com/v1/language/translate
요청변수란, 오픈 API를 호출할 때 함께 서버로 전송해야 하는 값이다.
요청변수에 한글이나 특수문자가 요청 변수값에 포함되어 있을 경우, 서버 전송 시 값이 깨지기 때문에 인코딩/디코딩 과정이 필요하다.

Kakao REST API (카카오톡, 카카오페이)

1. 먼저, 카카오 로그인 후에 사용자 토큰을 받아온다.

2. 사용자 토큰을 헤더에 담아 GET으로 요청한다.

GET /v1/api/talk/profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

 

3. 응답은 JSON 형태로 다음과 같은 정보를 포함한다.

{
 "nickName":"홍길동",
 "profileImageURL":"http://xxx.kakao.co.kr/.../aaa.jpg",
 "thumbnailURL":"http://xxx.kakao.co.kr/.../bbb.jpg",
 "countryISO":"KR"
}

Response Code Example
{
  "meta": {
    "code": 200,
    "response_time": {
      "time": 0,
      "measure": "seconds"
    }
  },
  "notifications": {},
  "response": {}
}

Error Code Example
{
  "meta": {
    "code": 500,
    "error_detail": "The user has not authorized or the token is invalid.",
    "error_type": "invalid_auth",
    "developer_friendly": "The user has not authorized or the token is invalid.",
    "response_time": {
      "time": 0,
      "measure": "seconds"
    }
  }
}

 

---

Best Web API Design Rules

1. 기본 URL에는 동사가 아닌 명사를 사용, 리소스마다 2개의 기본 URL을 유지하자.
/dogs (Collection), /dogs/1234 (Element)

2. 올바른 HTTP 메서드(POST, GET, PUT, DELETE)를 사용하자.
POST(create), GET(read), PUT(update), DELETE(delete)

3. 복수형 명사와 구체적인 이름을 사용하자.
/animals, /dogs

4. 자원 간의 관계를 간단히 하여 URL 계층이 깊어지는 것을 피하자.
GET /owners/5678/dogs?color=red

5. 오류 처리를 명확하게 하고 에러 스택은 절대 비공개 해야 한다.
6. 접두사 "V"로 버전을 지정하고 지속적인 버전 관리를 하자.
GET /v1/dogs

7. 데이터베이스에 없는 자원에 대한 응답일 경우 동사를 사용하자.
e.g.) Caculate, Translate, Convert ...

8. 속성의 네이밍은 Javascript의 관습을 따르고 카멜 케이스를 사용하자.
"createdAt": 123415125

9. 하위 도메인의 독립적인 API 요청 처리는 통일하자.
company.com
api.company.com (if not exists, redirect)
developers.company.com

10. 기타
권한 관리(OAuth)는 2.0을 사용하자.
필요한 경우, SDK로 API를 보완하자.
API Facade Pattern을 API 설계에 고려해라.