first
This commit is contained in:
230
safekiso_admin/content/doc/api_doc.md
Normal file
230
safekiso_admin/content/doc/api_doc.md
Normal file
@@ -0,0 +1,230 @@
|
||||
**(사)한국인터넷자율정책기구 KSS(KISO Safeguard System)API 서비스**
|
||||
## API 연동 안내
|
||||
|
||||
### 개요
|
||||
|
||||
KISO Safeguard System API 서비스는 제시된 문자열 중에 미리 준비된 욕설·비속어 DB에 포함된
|
||||
표현이 있는지를 빠르게 검사하고 그 결과를 돌려 주는 API 서비스 입니다.
|
||||
|
||||
- 사전 비교 방식 (2024년 4월 현재 80만여 표현)
|
||||
- 아호코라식(Aho-Corasick) 알고리즘으로 빠른 검색
|
||||
|
||||
|
||||
|
||||
### 호출 주소
|
||||
|
||||
```log
|
||||
https://www.safekiso.com/api/v1/filter
|
||||
\___/ \_______________/ \____/ \____/
|
||||
| | | |
|
||||
protocol domain version api name
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
### API 호출 파라메타
|
||||
|
||||
콘텐츠 타입은 application/x-www-form-urlencoded, 메쏘드는 POST로 호출 합니다.
|
||||
|
||||
|
||||
| location | name | mandatory | Description |
|
||||
|-------------|-------------|-------------|-------------|
|
||||
| header | x-api-key | `required` | API 키 |
|
||||
| body | text | `required` | 필터 검사 대상이 되는 문자열 |
|
||||
| body | mode | `required` | 필터 모드. quick인 경우 첫번째 매칭이 발견되면 더 이상 검색하지 않고 결과값을 리턴. normal인 경우 전체를 검사하고 그 결과를 리턴. filter인 경우 전체를 검사하고 그 결과로 필터된 단어를 필터 마스크(*)로 대체한 대체 텍스트까지 결과에 포함함. |
|
||||
| body | callback | `optional` | 비동기 처리 요청 응답 수신 url. 여기에 값이 설정되면 요청은 작업 큐에 저장된 후 처리 완료 후 해당 주소에 대한 호출로 결과를 리턴합니다. |
|
||||
| body | checksum | `optional` | API 키를 클라이언트에서 사용하려는 경우 만료 시간을 설정하고 검증하기 위한 체크값 |
|
||||
| body | ts | `optional` | 체크값 생성 근거가 되는 타임 스템프값 |
|
||||
|
||||
### API 호출 결과값
|
||||
|
||||
API 서버가 어떤 방식으로든 동작하고 있다면 서버는 HTTP(S) 호출에 대한 응답으로 반드시 200 [HTTP/1.1 - RFC2616에 명세된](https://www.ietf.org/rfc/rfc2616.txt)으로 응답합니다. 이 경우 표준 응답값과 별개로 본 서비스에서는 아래와 같은 Status.Code의 값을 이용하여 서비스의 상태와 호출 결과값을 표시합니다. 만약 표준 호출 응답이 200이 아닌 경우라면 본 서비스 자체가 아니라 로드 밸런서, 게이트 웨이 등 여러가지 레이어에서 서비스 제공이 불가능하여 응답을 보낸 것으로 판단할 수 있습니다. 이 경우에는 그 컨벤션에 맞춰 대응하시면 됩니다.
|
||||
|
||||
| Status.Code | Description |
|
||||
|-------------|-------------|
|
||||
| `2000 OK` | 모든 처리가 완료되어 정상적으로 결과를 되돌리는 경우 이 코드를 사용하게 됩니다. |
|
||||
| `2020 Accepted` | 호출 파라메타중 callback에 값이 설정된 경우 실제 요청에 대한 처리를 하지 않고 일단 작업큐에 저장한 후에 이 응답이 발생합니다. 이 응답은 지정된 callback 주소를 호출할때에 응답에 함께 포함된 TrackingId의 값을 참조하여 매치할 수 있습니다. |
|
||||
| `4000 Bad Request` | 어떤 이유로 지금 수신한 호출에 정상 처리가 불가능합니다. 보통의 경우 필요한 파라메타가 누락된 경우 또는 해당 파라메타에 부적절한 값이 들어가 있는 경우, 부가적인 체크섬 체크 옵션이 켜져있으나 체크에 실패한 경우 입니다. 구체적인 이유는 Status.Description의 메세지를 참고하여 조건을 수정한 후에 다시 호출해야 합니다.|
|
||||
| `4010 Unauthorized` | 요청을 인증할 API 키 값이 없는 경우 발생하는 오류 입니다. `4030 Forbidden` 오류와 다른 경우임에 주의해 주세요.|
|
||||
| `4030 Forbidden` | 서버에서 요청에 API 키값을 인식하였으나 해당 키가 적절한 권한을 가지지 않았다고 판정한 경우 발생합니다. 보안상의 이유로 4040과 같은 코드를 사용하지는 않는다는 점을 참고해 주세요. |
|
||||
| `4290 Too Many Requests` | 아이피를 기준으로 특정 클라이언트가 너무 많은 요청을 단위시간 안에 보낸 경우에 이 응답이 리턴됩니다. 서버측에서 사용자들의 입력을 처리하는 경우에는 이 값에 주의해서 미리 큰 값으로 설정해 주어야 하며, 관리자에게 문의하여 처리가 가능합니다. |
|
||||
| `5000 Internal Server Error` | 서버측의 문제로 요청에 대한 처리가 불가능한 경우 오류가 발생하였음을 알리기 위해 본 코드를 사용합니다. Description에서 보다 상세한 오류 메세지를 확인할 수 있으며 보통의 경우 이 오류는 잠시 후에 다시 시도하는 것으로 극복 가능합니다. |
|
||||
| `5030 Service Unavailable` | 현재 서비스가 점검중이므로 서비스 응답할 수 없는 경우 발생합니다. |
|
||||
|
||||
|
||||
### !!! 주의 !!!
|
||||
|
||||
여기에 명세된 Status.Code는 http의 호출 결과 상태 코드(http status code)와 다릅니다. 그 값을 기반으로 뒤에 0을 하나 더 붙여 만들어 진 것들로 의미를 연상하기 쉽도록 만들어 진 것이나 그대로 같은 의미가 아니고 둘은 서로 다른 값이니 참고하여 주세요. 예를 들어 Status.Code의 값이 4290인 경우에도 http status의 값은 200이 오는 것이 정상입니다. 이런 설정을 가진 이유는, API 서비스를 호출하는 과정에서 서버가 반응하지 않는 경우에는 http status의 값으로 상황을 판단하고 일단 호출 결과 http status의 값이 200이라면 이는 API 서버가 작성한 결과값이 도착했음을 의미한다고 봐도 좋습니다. http status의 값이 429가 오는 경우에는 KSS를 호스팅 하는 인프라에서 자체적으로 판단하여 호출수가 너무 많다고 판정한 경우입니다.
|
||||
|
||||
|
||||
### API 사용예
|
||||
|
||||
몇가지 방법으로 예를 보이면 아래와 같습니다.
|
||||
|
||||
|
||||
cURL
|
||||
|
||||
```sh
|
||||
curl --location --request POST 'https://www.safekiso.com/api/v1/filter' \
|
||||
--header 'x-api-key: <YOUR-API-KEY-HERE>' \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'text=검사할 문장을 이곳에 넣어 주세요.' \
|
||||
--data-urlencode 'mode=filter' \
|
||||
```
|
||||
|
||||
JavaScript - Fetch
|
||||
|
||||
```sh
|
||||
|
||||
var myHeaders = new Headers();
|
||||
myHeaders.append("x-api-key", "<YOUR-API-KEY-HERE>");
|
||||
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
|
||||
|
||||
|
||||
var urlencoded = new URLSearchParams();
|
||||
urlencoded.append("text", "검사할 문장을 이곳에 넣어 주세요.");
|
||||
urlencoded.append("mode", "filter");
|
||||
|
||||
var requestOptions = {
|
||||
method: 'POST',
|
||||
headers: myHeaders,
|
||||
body: urlencoded,
|
||||
redirect: 'follow'
|
||||
};
|
||||
|
||||
fetch("https://www.safekiso.com/api/v1/filter", requestOptions)
|
||||
.then(response => response.text())
|
||||
.then(result => console.log(result))
|
||||
.catch(error => console.log('error', error));
|
||||
|
||||
```
|
||||
|
||||
|
||||
NodeJs - Native
|
||||
|
||||
```sh
|
||||
var https = require('follow-redirects').https;
|
||||
var fs = require('fs');
|
||||
|
||||
var qs = require('querystring');
|
||||
|
||||
var options = {
|
||||
'method': 'POST',
|
||||
'hostname': 'www.safekiso.com',
|
||||
'path': '/api/v1/filter',
|
||||
'headers': {
|
||||
'x-api-key': '<YOUR-API-KEY-HERE>',
|
||||
'Content-Type': 'application/x-www-form-urlencoded',
|
||||
},
|
||||
'maxRedirects': 20
|
||||
};
|
||||
|
||||
var req = https.request(options, function (res) {
|
||||
var chunks = [];
|
||||
|
||||
res.on("data", function (chunk) {
|
||||
chunks.push(chunk);
|
||||
});
|
||||
|
||||
res.on("end", function (chunk) {
|
||||
var body = Buffer.concat(chunks);
|
||||
console.log(body.toString());
|
||||
});
|
||||
|
||||
res.on("error", function (error) {
|
||||
console.error(error);
|
||||
});
|
||||
});
|
||||
|
||||
var postData = qs.stringify({
|
||||
'text': '검사할 문장을 이곳에 넣어 주세요.',
|
||||
'mode': 'filter',
|
||||
});
|
||||
|
||||
req.write(postData);
|
||||
|
||||
req.end();
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
### 초당 호출수 과다 오류 발생하는 경우
|
||||
응답 코드 4290이 발생하는 경우에는 [netsafe@kiso.or.kr](mailto:netsafe@kiso.or.kr)로 연락을 주셔서 키 마다 설정되는 초당 최대 호출수 설정을 변경해 주셔야 합니다. 베타 서비스 시점에서 각 API 키의 초당 최대 호출수 제한은 100으로 설정되어 있으나, 이는 사전 예고 없이 조정된 후 공지될 수 있으니 참고해 주세요. 만약 기본 값보다 더 많은 초당 호출수가 필요한 경우에는 별도의 협약이 필요하니 [netsafe@kiso.or.kr](mailto:netsafe@kiso.or.kr)로 메일 주시기 바랍니다.
|
||||
|
||||
|
||||
### 비동기 방식으로 서비스를 호출하는 경우
|
||||
|
||||
callback에 콜백할 주소를 지정하면 KSS에서는 우선 다음과 같은 응답이 도착 합니다.
|
||||
```
|
||||
{
|
||||
"TrackingId": "7408a8f2-5843-59f5-8352-9ef2f80d89ec",
|
||||
"Status": {
|
||||
"Code": 2020,
|
||||
"Message": "Accepted",
|
||||
"Description": "Filter work created with trackingId 7408a8f2-5843-59f5-8352-9ef2f80d89ec"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
실제 주어진 문장에 대한 필터 작업이 끝난 후에는 지정된 웹 주소로 다음과 같은 코드가 동작 합니다.
|
||||
```
|
||||
let options = {
|
||||
uri: req.body.callback,
|
||||
method: 'POST',
|
||||
body: response,
|
||||
json: true,
|
||||
};
|
||||
|
||||
request.post(options, function (error, response, body) {
|
||||
localHandler.handleApiFinalResponse(req, response, {
|
||||
error: error,
|
||||
response: response,
|
||||
body: body,
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
응답(response)의 예는 아래와 같습니다.
|
||||
```
|
||||
{
|
||||
"TrackingId": "7408a8f2-5843-59f5-8352-9ef2f80d89ec",
|
||||
"Status": {
|
||||
"Code": 2000,
|
||||
"Message": "OK",
|
||||
"Description": ""
|
||||
},
|
||||
"Detected": [
|
||||
[
|
||||
3,
|
||||
"개자식"
|
||||
]
|
||||
],
|
||||
"Filtered": "이런 ***을 봤나.",
|
||||
"Elapsed": "0 s, 10.448 ms"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 클라이언트측에서 API 키를 사용하려는 경우
|
||||
|
||||
이 경우 먼저 [netsafe@kiso.or.kr](mailto:netsafe@kiso.or.kr) 메일로 사용하실 키를 알려 주시고 저희가 기반 설정을 마친 후에 구체적인 검증값 생성 방법과 테스트를 도와 드립니다. 이 방식에 대한 상세한 안내는 보안과 관련이 있으므로 부득이 메일로 개별 안내 하는 것에 대해 양해 부탁 드립니다.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 기타 API 서비스 이용 안내
|
||||
|
||||
<a class="font-semibold text-indigo-600 hover:text-indigo-500" href="/doc/guide" >서비스 이용 안내</a> 를 참고해 주세요.
|
||||
|
||||
|
||||
|
||||
|
||||
### License
|
||||
Copyright © 2023 [(사)한국인터넷자율정책기구](https://www.kiso.or.kr/)
|
||||
|
||||
Reference in New Issue
Block a user