담당자에게 이메일과 문자 발송요청중입니다.
잠시만 기다려주세요.

loading
[앱 서비스 구축을 위해 개발자가 하는 일 9] API 서버 개념과 API 문서 작성 디자인 및 개발
2016.09.30. 12:08

이전화를 바탕으로 서버에 대한 환경 설정을 진행했습니다.


전원주택을 건설하는 것으로 비유를 하자면 수도 및 가스관 연결, 땅 다지기 등의 작업을 했다고 생각하시면 됩니다.


이제 API서버를 개발해야 합니다.


이쪽 업계에서 일하다 보면 보통 API라는 이야기를 많이 듣게 됩니다.


그럼 API라는 것은 무엇일까요?

카카오의 API소개를 보면 아래와 같습니다. 바로가기 => https://developers.kakao.com/features/kakao

"카카오의 여러서비스들을 API로 만나보세요."



API란 말은 다들 많이 사용하고 무엇인지 알고 있지만 API는 "XX"이다 정확하게 말하는 경우도 없습니다.

왜 그런지 이유를 위키피디아를 찾아보면 굉장히 많은 뜻으로 쓰이고 있기 때문입니다.


[한글]

API(Application Programming Interface,응용 프로그래밍 인터페이스는)

응용 프로그램에서 사용할 수 있도록, 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻합니다.


[영문]

In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building software and applications.

A good API makes it easier to develop a program by providing all the building blocks, which are then put together by the programmer. 

An API may be for a web-based system, operating system, database system, computer hardware, or software library. 

An API specification can take many forms, but often include specifications for routines, data structures, object classes, variables, or remote calls. POSIX, Microsoft Windows API, the C++ Standard Template Library, and Java APIs are examples of different forms of APIs. 

Documentation for the API is usually provided to facilitate usage. 

The status of APIs in intellectual property law is controversial.


이중에 우리가 알아야할 개념에 대해서 알아보겠습니다. 


"기계와 기계의 소통을 위한 기능 혹은 명세" 입니다. 

예를 들어 사람의 경우 

A라는 사람과 B라는 사람이 있습니다. A라는 사람이 B라는 사람에게 정보를 전달하려면 의사소통을 해야합니다.
의사소통을 하려면 어떤 규칙이 필요합니다.
한국 사람이면 한국어라는 규칙을 이용해서 쓰고 미국사람이라면 영어를 사용할 겁니다.

예를 들어 기계의 경우 

아이폰 혹은 안드로이드에서 API 서버가 있습니다. 아이폰 혹은 안이드로이는 API 정보를 전달하려면 의사소통을 해야합니다.
의사소통을 하려면 어떤 규칙이 필요합니다. 
성능과 기능 필요에 따라 JSON이라는 규칙을 쓰거나 XML 등의 규칙을 사용할 것입니다.

이제 웹 혹은 앱에서 API에 대한 정의 한다면 

보통 앱 또는 웹 서비스 개발에서 다른 서비스에 소스는 공개하지 않으면서 권한에 따라 기능(데이터)을 제공하려고 할 때 사용합니다.

이런 규칙들을 바탕으로 우리의 서비스에 구글 지도나 네이버 로그인, 카카오톡 로그인 등의 기능을 활용할 수 있게 됩니다. 

그럼 이제 기능적인 요소에 대해 좀 더 알아 보겠습니다.

위에 규칙이 나옵니다. JSON과 XML입니다. 이에 대한 분석은 


라는 분석글을 참고하기 바랍니다.


사실 유저입장에서는 JSON이건 XML이건 몰라도 사용하는데 크게 상관없습니다.


유저에게 정보를 전달하는 속도가 중요하기 때문에 위의 규칙을 숙지하고 어떤 규칙으로 진행할지 정하고 API 개발에 들어가야 하기 때문입니다.


저는  JSON을 선호하기 때문에 JSON을 이용하는 방식으로 진행합니다.


이제 포맷도 정했으면 아래처럼 문서를 만듭니다.


 


그럼 이런 문서는 왜 만들까요?


이 문서는 개발자들간의 공유 및 팀원들과의 소통을 위해서 문서를 작성합니다.


프로젝트에 따라 IOS,안드로이드 개발자,서버 개발자, 미들웨어 개발자 등등


필요에 따라 개발자 수는 다릅니다. 이 모든것을 혼자할수도 있습니다.


혼자 작업하다보면 까먹는것도 생길 수 있고 혼동이 오는 부분을 방지하기 위함입니다. 


이런 이유들을 바탕으로 공지사항 목록 조회 API를 작성하는 예제 문서를 작성해 보겠습니다.




- API 설명 예시(다음은 공지사항 목록 조회 API에 대한 설명.)


인터페이스명

설명

공지사항 목록 조회

공지사항 목록을 리턴


■ 설명 : 공지사항 목록을 JSON 형태로 리턴 합니다


● Request 


TYPE : POST/GET HTTP/1.1 Encoding : UTF-8

URL : http://[IP]:[port]/v1/api/notice/index


▲ Parameter : 아래의 파라미터 값들로 요청합니다.


이름

설명

필수

page

페이지 번호


user_id

유저 아이디


Response


HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{

    "code": 200,

    "message": “요청 성공하였습니다.”,

    "data": {

             “list_count”: “1”,

             “notice_list:”[

                                   {

                                    "id": “123123123123adsacdsf”

                                    “title": “공지사항 제목",

                                    “author": "관리자",

                                    “date": "2015-07-02"

                                   }

                              ]

  }

}



◇ Response 속성


이름

설명

필수

code

Response 코드

O

message

Response 메시지

O

data

Response


└ list_count

공지사항 리턴 데이터 수

O

└ notice_list

공지사항 목록 데이터


    └ id

공지사항 고유번호

O

………………………

…………………………………



▼ Error : 공통상항과 똑같이 적용. 특별한 경우 없음



이제 이런 형식을 이용하여 각 서비스에 필요한 기능들을 정의합니다.

기획서가 있다면 보통 문서 정의하는데 만해도 몇일이 소요가 됩니다.

이렇게 문서를 작업하고 나면 이제 미들작업을 시작하게 됩니다.


다음화에는 API 예제를 만들어 보겠습니다.



이전 내용은 이곳에서 보시면 됩니다.

 

[개발자가 하는 일 1] 서버 구축에 앞서.. 

[개발자가 하는 일 2] 운영체제 선택

[개발자가 하는 일 3] 본격적인 서버 구축 - 기본 설정 및 확인

[개발자가 하는 일 4] 본격적인 서버 구축 - vsftpd설치

[개발자가 하는 일 5] 본격적인 서버 구축 - 웹 서버 설치

[개발자가 하는 일 6] 본격적인 서버 구축 - 웹 어플리케이션 서버 설치

[개발자가 하는 일 7] 본격적인 서버 구축 - 도메인과 서브도메인

[개발자가 하는 일 8] 본격적인 서버 구축 - 로드밸런싱을 위한 Haproxy

 


참조

개발의뢰