devunt/ozinger-api.md

## ozinger-api.md

      
    Raw
  

              ozinger-api.md
            
          
    오징어 IRC 네트워크 API 문서

관련 IRC 명령


/s registerapp ? (앱 최초 등록 및 토큰 발급)
/s enableapp ? (앱을 특정 채널에서 사용 가능하도록 활성화)
/s disableapp ?
/s unregisterapp ?

API 명세

REST API


Endpoint: https://api.ozinger.org/chat
HTTP 엔드포인트는 deprecated 되었습니다. HTTPS를 써 주세요.

푸시 알림 등 단순 메시지 전송에 쓸 수 있다. 쓰기 전용.
모든 요청에 X-OZ-TOKEN: {token} 헤더 혹은 token 필드를 포함해야 함. 토큰은 \d+@[a-h0-9]{32} 의 형식을 띄고 있다.
요청은 POST로 이루어져야 하며, POST body에 다음 JSON을 포함해야 한다.
{
  "token": "헤더에 포함시켰을 경우 없어도 됨",
  "sender": "메시지를 전송할 사용자 닉네임 [A-Za-z0-9가-힣_]{1,16}]",
  "target": "타겟 채널 이름 (앞 # 포함)",
  "message": "전송할 메시지"
}
WS API


Endpoint: wss://api.ozinger.org/chat
plain websocket 엔드포인트는 deprecated 되었습니다. Secure websocket 엔드포인트를 써 주세요.

단순 메시지 전송이 아닌, IRC의 메시지를 읽어오는 등 타 플랫폼과의 브릿지나 IRC 봇 구현을 위해 쓸 수 있다. 읽기/쓰기 가능.
모든 요청과 응답은 JSON으로 이루어지며, 요청은 action 필드를, 응답은 code 필드를 포함한다.
첫번째 요청은 필히 token 필드를 포함한 action=authenticate 요청이어야 한다. 그 뒤로는 강제적으로 action=message 요청만 쓸 수 있다.
샘플 웹소켓 플로우

// 인증 요청
{
  "action": "authenticate",
  "token": "92@36fdb62a78214111a24457b894618634"
}

// 인증 응답
{
  "code": "authenticated",
  "name": "testapp",
  "slug": "test",
  "channels": ["#ozinger"]
}

// 메시지 쓰기 요청
{
  "action": "message",
  "sender": "devunt",
  "target": "#ozinger",
  "message": "안녕하세요 API로 메시지를 씁니다"
}

// 메시지 쓰기 응답
{
  "code": "sent"
}

// 남의 메시지 받기
// origin 필드는 IRC에서 온 메시지의 경우 *, 타 앱에서 온 메시지인 경우 해당 앱의 slug가 표시
{
  "code": "message",
  "origin": "*",
  "sender": "otheruser",
  "target": "#ozinger",
  "message": "와 API로 IRC를 할 수 있다니 신기하네요!"
}
응답 타입


코드
설명


authenticated
성공적으로 인증됨
(action=authenticate 웹소켓 요청에 응답으로 올 수 있음)


sent
성공적으로 발송됨
(action=message 웹소켓 요청 혹은 /chat REST API 요청에 응답으로 올 수 있음)


invalid_token
아직 인증하지 않았거나 제공된 토큰이 올바르지 않음


invalid_payload
필수 필드가 존재하지 않거나 잘못된 내용을 담고 있음


unauthorized_channel
해당 채널에 메시지를 발송할 수 있는 권한이 없음
(IRC에서 /s enableapp 명령을 통해 활성화해야 함)
코드	설명
authenticated	성공적으로 인증됨 (`action=authenticate` 웹소켓 요청에 응답으로 올 수 있음)
sent	성공적으로 발송됨 (`action=message` 웹소켓 요청 혹은 `/chat` REST API 요청에 응답으로 올 수 있음)
invalid_token	아직 인증하지 않았거나 제공된 토큰이 올바르지 않음
invalid_payload	필수 필드가 존재하지 않거나 잘못된 내용을 담고 있음
unauthorized_channel	해당 채널에 메시지를 발송할 수 있는 권한이 없음 (IRC에서 `/s enableapp` 명령을 통해 활성화해야 함)