분류 전체보기
-
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를 통해 정보와 도구를 제공하고 있다..
-
[Git blog 만들기] - 2. Git에서 자주 쓰이는 커맨드 정리git과 Markdown 2022. 4. 20. 21:07
지난번 포스팅에서는 git의 기본 커맨드에 대해서 알아봤다면 이번 포스팅에서는 git에서 자주 사용되는 커맨드의 아주 기본! 에 대해서만 간단하게 정리해보려고 한다. 해당 커맨드에 대해서 자세하게 설명하려면... 끝도 없을 것이다. 해당 커맨드에서 대해서 더 많은 정보가 궁금하다면 역시나 깃 공식 홈페이지를 참고하면 된다! 아주아주 잘 정리된 문서를 확인할 수 있다. git 도움말 불러오기: git help git 커맨드에 대해서 도움이 필요할 때 구글링으로 검색하면 많은 해답을 찾을 수 있지만 git help 커맨드를 사용해 빠르게 확인할 수도 있다. $git help $git help [커맨드 입력] // 사용법이 궁금한 git의 커맨드를 입력합니다. 매뉴얼의 내용을 출력합니다. 실제 출력되는 화면은..
-
[Git blog 만들기] - 1. Git의 필요성과 Git 기본 개념git과 Markdown 2022. 4. 5. 20:40
한동안 git blog 만드는 일에 빠져있어서 포스팅을 못했다.😅 git을 처음 사용해보기 때문에 어려움도 많았지만 구글링을 해보면 git과 관련된 자료가 아-주 아주 아주 x 100 많아서 스스로 정리하면서 개념을 정리해보고자 한다. Git 왜 필요할까? 처음에 git을 알게 되었을 때는 개발자들만 사용하는 줄 알았다. 하지만 테크니컬 라이터에 관심을 가지게 되고 실제로 모 it 기업에 면접을 보러 갔을 때 'git을 사용해 보셨나요?'라는 질문을 들었고, 나는 사용해보지 못했다고 대답을 했다. 그때부터 '아 테크니컬 라이터도 git을 다뤄보는 게 좋겠구나!'라는 생각이 들었다. 다행히도(?) git을 사용해보지 않았다고 면접에서 떨어지진 않았지만 우대사항에 들어가는 git을 나도 공부해보면 좋지 않을..