Open API와 API 명세

컴퓨팅의 역사는 점점 더 높은 수준의 추상화의 길이다. API가 유명해지면서, 소스코드에 대해 아무것도 모르는 유저들이 원격 서비스와 쉽게 사용할 수 있도록 API의 작동방식을 지정할 수 있는 인터페이스가 개발되는데 이를 API 명세 언어(API specification languages)라고 부른다. 이 언어는 API 개발을 다양한 방향으로 돕는다. 클라이언트와 API를 만드는 사람들 사이에 정보를 더 쉽게 공유할 수 있게 해주고 또한 많은 자동화를 가능하게 해준다.


API Specifications

일부 API는 엄격하게 정의된 프로토콜을 따른다. 하지만 RESTful API는 일반적인 원칙들이 제시되어 있지만 지켜야 하는 엄격한 프로토콜은 없다.SOAP API는 엄격한 프로그래밍 규칙에 따라 구조를 지정해야 한다.즉, API 정의는 컴퓨터가 이해할 수 있는 방식으로 쉽게 작성되어야 한다. 이러한 종류의 API에 대해 많은 범용 자동화를 쉽게 만들 수 있다. 

API Specification 용어
API description format : API 설명 자체를 따를 수 있는데, 이는 API가 무엇을 담고 있고 할 수 있는지를 설명하는 실제 메타데이터이다. 
API specification (API 명세서/API 설계서) 는 다양한 종류의 설명 형식과 문서를 포괄하는 포괄적인 용어이다.
API 설명 문서는 특정 API 설명 형식으로 작성된 특정 API에 대한 설명을 포함하는 문서이다.

API 명세서 종류

- RAML (Restful API Modeling Language)
https://raml.org/
이 언어는 YAML 형식을 따른다.YAML은 사람이 읽을 수 있는 파일 형식으로 몇 가지 간단한 규칙을 따름으로써 데이터를 쉽게 구성할 수 있다. 참고 사이트 : https://yaml.org/spec/1.2.2/
대부분의 구조는 API를 생각하고 설계해야 하는 방식과 일치하는 방식으로 구축된다. 이는 API를 미리 계획하고 그 설계와 일치하는 API를 만드는 설계 우선 API를 만들려는 경우에 RAML을 선택하는 것이 좋다.

- API Blue print
https://apiblueprint.org/
이 언어는 마크다운 형식을 사용한다. 

참고사이트 : https://www.markdownguide.org/cheat-sheet/
마크다운을 이용해서 이 형식을 읽으면 더 이해하기 쉽다. 
만약 포스트맨으 이용하려고 한다면, 먼저 포스트맨에서 사용할 수 있는 포맷으로 바꾸는 툴을 사용해야 한다.


- OpenAPI/Swagger
https://github.com/OAI/OPENAPI-Specification
가장 많이 사용하는 API용어는 OpenAPI이다. 원래는 Swagger라고 불렸기 때문에 OAS를 지원하는 많은 도구들이 swagger tools라고 불리는 반면 사양 자체는 OpenAPI라고 한다. 이 언어는 많은 툴로부터 지원을 받고 유연하고 강력하다. 큰 툴셋과 광범위한 채택으로 인해 사실상 API의 표준이라고 볼 수 있다. 어떤 것을 사용할지 확실하지 않을때는 디폴트로 OpenAPI를 사용하는것이 최선이다.

 

OpenAPI Specification

swagger editor tool : https://editor.swagger.io/ (no download)
처음 사이트에 접속시 다음과 같은 캡처 화면을 볼 수 있다.

오른쪽 화면에서 미리보기를 보여준다. 왼쪽에서 수정되면 바로 오른쪽에 결과로 확인이 가능하다.
예시는 아래 화면을 참고하면 된다.

info 영역 : 여기서 API 개체의 기본 데이터가 정의된다. 최소 제목, 설명 및 버전 옵션을 포함해야 한다. 그리고 API에 대한 메타데이터를 지정하는데 도움이 되는 몇가지  다른 옵션이 하이레벨의 태그가 있는데 필수적이진 않다.

paths 영역 : 이 영역은 중요하고 많은 옵션들이 있다. 엔드포인트를 정의하는 곳이며, 엔드포인트 아래에서 해당 엔드포인트에서 사용할 수 있는 다양한 행동을 정의할 수 있다. 또한 각 엔드포인트와 행동들에 관한 다양한 디테일(ex: 어떤 종류의 데이터를 필요로 하는지)을 정의할 수 있다. 이 영역에는 API 설명의 대부분이 포함되어 있다. 
/pet 엔드포인트에서 다음은 어떤 호출을 할 것인지를 정하는데 이때 put, post를 호출할 수 있다. 이 다음 작업은 엔드포인트에 대한 정보를 정의하는 스펙의 일부이다. summary, operationID 등이 여기에 포함된다.

requestBody : API 호출의 본문에 무엇을 입력해야 하는지를 정의한다. 여기서는 내용 유형(application/json, application/xml)을 정의한 다음 그 아래에서 이 내용이 따라야 할 스키마,구조를 정의한다. 스키마는 $ref 키를 사용하여 참조된다.이것은 문서 다른 부분에 저장된 값을 가리키는 키이다. 
responses : API호출의 또 다른 중요한 부분은 response이다. 스펙은 응답 영역에서 API가 제공할 수 있는 각 응답에 대해 수행해야 할 작업을 정의한다.
paths 영역에는 각 엔드포인트가 수행할 수 있는 작업의 대부분이 설명되어있지만, 이러한 요청의 본문에 대한 스키마는 스키마라는 문서의 다른 부분에 정의되어 있다.


API 스키마 정의
shema는 기본적은 계획이다. 보통 모델이나 이론의 형태이다.
스키마는 소프트웨어 개발에서 일반적으로 사용된다. 예를 들어, 데이터베이스에서 스키마는 다양한 테이블이 서로 연결되는 방식을 보여준다. API 스키마는 데이터가 어떻게 구성되어야 하는지를 보여준다. 응답에 어떤 내용이 포함되어야 하는지, post나 put request에 어떤 데이터가 포함되어야 하는지를 보여준다.