API 통신 기초

• API(Application Programming Interface): 프로그램끼리 데이터를 주고받기 위해 정해놓은 약속. 한 프로그램이 인터넷/네트워크를 통해, 이 API 서버에 "이런 요청 보낼 테니까 이런 형식으로 응답해 줘"라고 약속된 방식으로 통신.
  • 자사 프로젝트는 그중에서도 웹 API, 정확히는 HTTP를 사용하는 API 서버.

• 서버 : 요청 받아 처리하고 응답 돌려주는 쪽.

• 클라이언트 : 서버에 요청 보내는 쪽. 자사 프로젝트는 "서버"가 클라이언트 역할도 하고, 반대로 자사 프로젝트가 서버에 요청을 보낼 때는 자신이 클라이언트가 되기도 한다.(양방향 통신)
  즉, 하나의 프로그램이 상황에 따라 서버가 되기도 하고 클라이언트가 되기도 함.

• HTTP 요청과 응답
  : HTTP는 클라이언트와 서버가 데이터를 주고받을 때 쓰는 통신규약. 하나의 HTTP 통신은 항상 "요청 -> 응답" 한쌍으로 이루어진다.

• 요청(Request)에 들어가는 것

  • URL(주소) : 어떤 서버의 어떤 기능을 호출할지 지정하는 경로. 예를 들면 http://localhost:5111/api/engine/run
  • 메서드 : 무엇을 하고 싶은지 나타내는 동사
    • GET
    • POST
    • PATCH
    • DELETE
  • 헤더(Header) : 요청에 대한 부가 정보. 예를 들면, 본문이 JSON이라는 표시, 인증 토큰 등.
  • 본문(Body) : 실제로 보내는 데이터. 보통 JSON 형식.

• 응답(Response)에 들어가는 것

  • 상태 코드(Status code) : 요청의 성공 실패 여부를 숫자로 나타냄.
    • 200번대 : 200 OK = 정상 처리, 204 No Content = 성공했지만 돌려줄 내용 없음
    • 400번대 : 클라이언트쪽 잘못. 400 Bad Request = 요청 형식이 잘못됨, 404 Not Found = 찾는 대상 없음
    • 500번대 : 서버쪽 오류
  • 본문(Body) : 서버가 돌려주는 실제 데이터. 보통 JSON 형식.

---

• JSON
  데이터를 텍스트로 표현하는 형식. API 통신에서 본문(Body)에 담기는 데이터의 표준 포맷이다.

{ "dxfPath : "C:/path/input.dxf", "excelPath": "C:/path/equipment.xlsx" }

• 서버는 이 JSON 텍스트르 받아서 프로그램이 다룰 수 있는 객체(클래스 인스턴스)로 변환.
• 반대로 응답을 보낼 때는 객체를 다시 JSON 텍스트로 변환해서 내보낸다. 이 변환 과정을 직렬화(Serialize : 객체 -> JSON), 역직렬화(Deserialize, JSON -> 객체)라고 부름.

---

• 엔드포인트(Endpoint)와 라우팅(Routing)
  엔드포인트란, API가 제공하는 "요청을 받는 개별 주소"를 가리킨다.

POST /api/engine/run : 엔진 실행 요청
GET /api/enigne/status/{pid} : 특정 프로세스 상태 조회
GET /api/engine/list : 전체 프로세스 목록 조회
DELETE /api/engine/stop/{pid} : 프로세스 중지
POST /api/engine/cancel/{resultId} : 작업 취소
GET /api/engine/jobs : 실행중인 작업 목록

서버가, 들어온 요청의 주소(URL)와 메서드를 보고 "이건 어떤 코드가 처리해야 하는가"를 결정해서 연결하는 과정이 라우팅이다.

서버는 두가지 방식으로 동작할 수 있다

• 요청-응답형 : 클라이언트가 요청을 보내면 서버가 즉시(또는 처리 후) 응답을 돌려주는 방식. 자사 프로젝트의 컨트롤러가 이 방식에 해당.
• 백그라운드 처리형 : 클라이언트의 요청과 무관하게, 서버가 스스로 주기적으로 어떤 동작(다른 서버에 작업이 있는지 확인 등)을 반복하는 방식. (ClaimWorker)

ClaimWorker가 주기적으로 "할일 있어?"라고 물어봄(POST)
끝나면 "이렇게 끝났어"라고 알려줌 (PATCH)
파일 저장소(S3)나 다른 웹서버와 파일 주고받음 (FileTransferSevice가 처리)