API
-
API 문서화 공부하기 - 8 깃북과 마크다운으로 API 문서 정리하기API 2022. 7. 11. 20:41
1 - 7 포스팅을 통해 API에 대해서 공부해보았다. 공부한 내용을 바탕으로 작성한 Surfreport 예시를 이미 익숙한 툴인 깃북과 마크다운 문법으로 정리해보려고 한다. API가이드를 작성할 때 자주 사용되는 툴로는 Swagger와 앞서 잠깐 살펴보았던 Postman도 있다. 아직 본격적으로 사용해보지는 않았지만 API에 대해서 공부하면서 언젠가 사용해볼 기회가 있지 않을까?_? gitbook 먼저 깃북에서는 API를 작성할 수 있는 블록을 제공한다. API Method를 클릭하면 아래와 같은 블록이 생성된다. 이 블록에 입력 값을 입력만 해주면 이제까지 봤던 API문서의 형태로 정리할 수 있다. 요새 깃북을 사용해보고 있어서 깃북을 통해 정리해보려고 했다. 하지만 깃북을 사용하다 보니 다른 툴을 ..
-
API 문서화 공부하기 7 - 응답 예제와 응답 스키마API 2022. 6. 30. 22:49
이사 준비로 어영부영 6월이 지나갔다. 이사를 무사히 마쳤으니 다시 열심히 포스팅해야겠다! 😁 응답 예제와 응답 스키마 응답 예제는 요청 예제의 샘플 응답을 보여준다. 응답 예제는 모든 매개변수를 포괄하지는 않지만 요청 예제에서 전달된 매개변수와 일치해야 한다. 응답을 통해 개발자는 리소스에 원하는 정보, 형식 및 해당 정보가 구조화되고 레이블이 지정되는 방식이 무엇인지 알 수 있다. 응답에 대한 설명을 응답 스키마라고 한다. 응답 스키마는 반환될 수 있는 각 속성, 각 속성에 포함된 내용, 값의 데이터 형식, 구조 및 기타 세부 정보를 나열하여 보다 포괄적인 방식으로 응답을 문서화한다. 응답 스키마 살펴보기 응답 예제와 응답 스키마의 차이는 무엇일까? 응답 예제는 요청 예제와 일치해야 한다. 요청 예제..
-
API 문서화 공부하기 6 - 요청 예시API 2022. 6. 2. 20:16
요청 예시 살펴보기 요청 예시에는 엔드포인트를 사용하는 샘플 요청이 포함되어 있으며 일부 매개변수를 보여준다. 요청 예제는 모든 매개변수를 표시하지는 않지만 매개변수를 가능한 많이 보여주는 것이 좋다. 지난번 살펴본 토스페이 API 가이드에서는 오른쪽에 샘플 요청과 응답을 보여주고 있다. 다양한 언어들로 요청 예제를 제공하고 있지만 위 예시는 curl 형식의 예제이다. 일반적으로 curl을 사용하여 샘플 요청을 표시한다. curl은 요청에 필요한 헤더 정보와 요청과 함께 사용된 방법을 보여준다. ✋curl이란? 다양한 매개변수와 메서드를 사용하여 HTTP 요청을 실행할 수 있는 command line이다. curl을 사용할 때는 curl입력 후에 다음에 출력을 받아올 URL을 추가하여 작성한다. HTTP..
-
API 문서화 공부하기 5 - 매개변수API 2022. 5. 25. 21:13
매개변수 예시 살펴보기 매개변수(Parameter)는 엔드포인트와 함께 전달할 수 있는 옵션이다. 헤더 매개변수, 경로 매개변수 및 쿼리 문자열 매개변수와 같은 여러 유형의 매개변수가 있다. 매개변수의 예시는 다음과 같다. 토스 페이먼츠에서는 문서 옆에 코드 예제를 같이 보여주기 때문에 표를 더 간단하게 작성한 것 같다. Type이나 Required 열을 별도로 두지 않고 parameter name 아래에 같이 작성한 것을 확인할 수 있다. API문서에서 매개변수들은 대부분 아래 표 형태에서 크게 벗어나지 않는다. Parameter Required/Optional Description Data Type format Optional - String 문서 작성 시 주의해야 할 사항 매개변수 유형에 관계없이 ..
-
API 문서화 공부하기 4 - 엔드포인트와 메서드API 2022. 5. 18. 19:51
엔드포인트(Endpoint)는 리소스에 액세스 하는 방법을 의미하고 메서드(Method)는 리소스와의 상호작용을 의미한다. 동일한 리소스에는 일반적으로 경로와 메서드가 다르지만 동일한 리소스에 대해 다른 정보를 반환하는 엔드포인트가 있다. 엔드포인트에는 "API 문서화 공부하기 3"에서 다루었던 리소스 설명과 유사하지만 간단한 설명이 존재한다. 또한 엔드포인트에는 모든 엔드포인트의 기본 경로가 아니라 리소스 URL의 마지막 경로만 표시된다. 엔드포인트 예시 아래 이미지는 토스페이 결제 상태 확인에 대한 엔드포인트 예시이다. API 문서의 대부분은 엔드포인트를 중심으로 작성되기 때문에 엔드포인트는 문서에서 강조 효과를 주는 방식으로 작성되어 있는 경우가 많다. 엔드포인트는 개발자가 요청을 수행하기 위해 구..
-
API 문서화 공부하기 3 - REST API 문서 섹션과 리소스 설명API 2022. 5. 11. 20:49
API문서 작성을 하는 테크니컬 라이터는 문서 프로젝트를 처음부터 시작하지는 않는다. 내부 위키 페이지에 있는 정보들을 활용해서 가공해야 한다. 대부분 이 문서들은 팀 내부에 있는 엔지니어들만 알아볼 수 있는 내용들과 정리되지 않은 내용들로 이루어져 있다. 테크니컬 라이터는 이 정보를 사용자가 알아볼 수 있는 정보로 바꾸는 역할을 수행한다. API 문서를 작성해보는 실습을 하기 위해서 공부를 하고 있는 사이트에서 가상의 위키 페이지를 제공해주었다. Surfreport API에 대한 위키 페이지이다. (이런 식으로 가공되지 않은 정보들이 올라온다는 말인 걸까? 실제로 IT회사에서 근무해보지는 않아서 모르겠다.🙄) 보다시피 예제로 제공된 위키 페이지는 정보가 구조화되어있지 않고 사용자가 원하는 정보를 한눈에..
-
API 문서화 공부하기 2 - API 호출하기, JSON 규칙API 2022. 5. 9. 21:07
API 문서를 작성해보기 전에 실제 REST API를 사용해서 REST API에 대해서 이해하고 개발자가 어떤 작업을 수행하는지 알아볼 수 있다. 여기서 사용하는 툴은 ATOM과 Postman이다. https://openweathermap.org/ Сurrent weather and forecast - OpenWeatherMap Leaving everything behind, people are fleeing conflict in Ukraine. They need shelter, food, and water. When you subscribe to our service, you can join us to help with donation of just of 20. Openweather will add 4..
-
API 문서화 공부하기 1 - API문서의 필요성과 REST APIAPI 2022. 5. 2. 21:23
API 공부하기 좋은 사이트를 발견해서 이번에는 API 문서화에 대해서 공부해보려고 한다! 내 분야는 아니어서 많은 공부를 해봐야 될 것 같다. 이제까지 내가 작성해왔던 제조업에서의 일반적인 GUI 설명서와는 많이 다르다는 것이 느껴진다.🙄 예를 들어 이제까지 배포해왔던 파일은 PDF 형식이라면 API문서는 주로 웹 형식으로 배포된다는 차이도 있고.. 어쨌든 API에 대해서 대충 개념은 알고 있으니 이제 실습을 해볼 차례다. 왜 TW가 API를 공부해야 할까? 첫 번째로는 대규모 시스템 대신 웹사이트는 API를 통해 필요한 서비스를 제공하고 있다. 예를 들어 웹사이트에서 로그인 기능을 만드는 대신 카카오 로그인 서비스를 사용할 수 있다. 실제로도 많은 서비스에서 API를 통해 정보와 도구를 제공하고 있다..