Profanity Filter API 문서

이 API문서는 profanity-api 프로젝트의 API를 설명합니다.

포함되면 좋을것 같은 내용이나 수정이 필요한 내용은 언제든지 이슈 혹은 PR을 통해 알려주세요.

1. Overview

이 서비스는 한국어와 영어 비속어를 모두 검출하고 필터링할 수 있는 무료 API입니다.

1.1. 주요 특징

경량 필터링 엔진: 정규식과 비속어 데이터베이스를 활용한 효율적인 필터링
고성능 검사: `아호코라식 알고리즘`을 사용하여 빠르고, 정확한 비속어 검출
다양한 필터링 모드: 빠른 검사(QUICK), 일반 검사(NORMAL), 대체 검사(FILTER) 지원
KISO 호환성: [KISO 이용자 보호 시스템 API](https://www.safekiso.com/)와 유사한 스펙으로 구현

1.2. 이용 대상

이 API는 주로 다음과 같은 사용자를 위해 설계되었습니다:

포트폴리오나 취미 프로젝트를 개발하는 학생 및 개발자
비영리 서비스를 운영하는 소규모 단체
비용은 최소화하면서 기본적인 비속어 필터링이 필요한 웹사이트/앱

예산 제약 없이 상업적 서비스에 활용하실 경우에는 [KISO 이용자 보호 시스템 API](https://www.safekiso.com/)를 권장합니다(월 약 7만원).

이 서비스는 개인 서버로 운영되므로 가용성은 보장되지 않지만, 기본적인 비속어 필터링 기능을 무료로 제공하는 데 의의가 있습니다.

1.3. Note

정규식과 비속어 데이터베이스를 이용한 경량형 비속어 필터링 모델입니다.
비속어 검사의 경우 `아호코라식 알고리즘`을 사용하여 빠르게 검사합니다.
원색적인 욕설의 경우 대부분 필터링이 가능합니다.
[KISO 이용자 보호 시스템 API 서비스](https://www.safekiso.com/)의 스펙과 유사하게 구현되어 있습니다.
영어 욕설의 경우 몇몇 단어들은 포함되어있지만 모든 단어가 포함되어있지는 않습니다. 추가적인 단어를 추가하고 싶으시면 이슈를 등록해주세요.

2. 기타

2.1. 헬스 체크

서버 상태를 확인하기 위한 API입니다. 이 API는 서버의 상태를 확인하는 데 사용됩니다.

health 요청 시 200 상태와 OK 응답을 반환합니다.

Request

$ curl 'https://api.profanity-filter.run/api/v1/health' -i -X GET

$ http GET 'https://api.profanity-filter.run/api/v1/health'

Response

OK

HTTP/1.1 200 OK
Content-Type: text/plain;charset=ISO-8859-1
Content-Length: 2

OK

서버 상태를 확인하기 위한 API입니다. 이 API는 서버의 상태를 확인하는 데 사용됩니다.

PING 요청 시 PONG 응답을 반환합니다.

Request

$ curl 'https://api.profanity-filter.run/api/v1/ping' -i -X GET

$ http GET 'https://api.profanity-filter.run/api/v1/ping'

Response

PONG

HTTP/1.1 200 OK
Content-Type: text/plain;charset=ISO-8859-1
Content-Length: 4

PONG

3. 클라이언트

3.1. 신규 등록

사용자 정보를 등록 후 API Key를 발급 받을 수 있는 API입니다 발급된 API는 반드시 안전하게 보관해주세요

생성 시 입력하는 정보는 최대한 실제 정보를 입력해주세요 (테스트용 정보 사용을 권장하지 않습니다)
비정상적인 발급 요청등은 무통보 제거 될 수 있습니다
- name에 ???로만 등록되는 경우 확인 혹은 문의 바랍니다.
또한 요청 서버의 인코딩 설정을 확인해주세요
등록 후 정보확인 API 를 통해 등록된 정보를 확인할 수 있습니다

$ curl 'https://api.profanity-filter.run/api/v1/clients/register' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "name" : "팀 보틀노트",
  "email" : "bottlenote@email.com",
  "issuerInfo" : "도메인(https://api.profanity-filter.run)  ,  연락처(010-1234-5678)",
  "note" : "학원에서 진행하는 팀 프로젝트 입니다. 피드 작성 시 비속어 검증을 위해 신청 합니다."
}'

Request

{
  "name" : "팀 보틀노트",
  "email" : "bottlenote@email.com",
  "issuerInfo" : "도메인(https://api.profanity-filter.run)  ,  연락처(010-1234-5678)",
  "note" : "학원에서 진행하는 팀 프로젝트 입니다. 피드 작성 시 비속어 검증을 위해 신청 합니다."
}

Path Type Description

Path	Type	Description
`name`	`String`	이름 또는 조직명
`email`	`String`	이메일
`issuerInfo`	`String`	발급자 정보
`note`	`String`	메모

name

String

이름 또는 조직명

email

String

이메일

issuerInfo

String

발급자 정보

note

String

메모

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "name" : "팀 보틀노트",
    "email" : "bottlenote@email.com",
    "apiKey" : "apiKey",
    "note" : "학원에서 진행하는 팀 프로젝트 입니다. 피드 작성 시 비속어 검증을 위해 신청 합니다."
  }
}

Path Type Description

Path	Type	Description
`status`	`Object`	응답 상태 정보
`data`	`Object`	응답 데이터
`data.name`	`String`	등록된 클라이언트 이름
`data.email`	`String`	등록된 클라이언트 이메일
`data.apiKey`	`String`	발급된 API 키
`data.note`	`String`	등록된 메모

status

Object

응답 상태 정보

data

Object

응답 데이터

data.name

String

등록된 클라이언트 이름

data.email

String

등록된 클라이언트 이메일

data.apiKey

String

발급된 API 키

data.note

String

등록된 메모

3.2. 정보확인

발급된 API 키를 사용하여 가입 시 작성한 클라이언트 정보를 확인합니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients' -i -X GET \
    -H 'x-api-key: p7NGpUcnJppIXkR-vRvtLjv_1ZRrCDkZSX_lQFTS_mE'

Request

Name Description

Name	Description
`x-api-key`	클라이언트 API 키

x-api-key

클라이언트 API 키

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "id" : "4e35ca95-1bdc-48dc-b38d-2db0307c24ad",
    "email" : "bottlenote@email.com",
    "issuerInfo" : "도메인(https://bottle-note.com)  ,  연락처(010-1234-5678)",
    "note" : "학원에서 진행하는 팀 프로젝트 입니다. 피드 작성 시 비속어 검증을 위해 신청 합니다.",
    "permissions" : [ "READ", "WRITE" ],
    "issuedAt" : "2021-08-01T00:00:00"
  }
}

Path Type Description

Path	Type	Description
`status`	`Object`	응답 상태 정보
`data.id`	`String`	클라이언트 식별자
`data.email`	`String`	클라이언트 이메일
`data.issuerInfo`	`String`	클라이언트 발급 정보
`data.note`	`String`	클라이언트 메모
`data.permissions`	`Array`	권한 목록
`data.issuedAt`	`String`	발급일

status

Object

응답 상태 정보

data.id

String

클라이언트 식별자

data.email

String

클라이언트 이메일

data.issuerInfo

String

클라이언트 발급 정보

data.note

String

클라이언트 메모

data.permissions

Array

권한 목록

data.issuedAt

String

발급일

3.3. 이메일 인증 코드 발송

발급한 이메일을 통해 인증 코드를 전송합니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients/send-email?email=email%40email.com' -i -X GET

Request

Parameter Description

Parameter	Description
`email`	이메일 주소

email

이메일 주소

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : "send email"
}

Path Type Description

Path	Type	Description
`data`	`String`	전송 결과

data

String

전송 결과

3.4. 이메일 인증 코드 검증 및 결과 확인

이메일과 코드를 확인해 인증합니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients/send-email' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "email" : "email@email.com",
  "code" : "123456"
}'

Request

{
  "email" : "email@email.com",
  "code" : "123456"
}

Path Type Description

Path	Type	Description
`email`	`String`	이메일 주소
`code`	`String`	인증 코드

email

String

이메일 주소

code

String

인증 코드

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "apikey" : "apiKey-123456"
  }
}

Path Type Description

Path	Type	Description
`data`	`Object`	인증 결과
`data.apikey`	`String`	해당 이메일로 발급된 API 키

data

Object

인증 결과

data.apikey

String

해당 이메일로 발급된 API 키

3.5. 클라이언트 폐기

발급된 API 키를 사용하여 클라이언트 정보를 폐기합니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients' -i -X DELETE \
    -H 'x-api-key: KhxIV7OHqy8jU2o1PXop11VH4ansZ5uxBgtBl3e-9Fo'

Request

Name Description

Name	Description
`x-api-key`	클라이언트 API 키

x-api-key

클라이언트 API 키

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : true
}

Path Type Description

Path	Type	Description
`data`	`Boolean`	폐기 성공 여부

data

Boolean

폐기 성공 여부

3.6. 클라이언트 정보 업데이트

발급된 API 키를 사용하여 클라이언트 정보를 업데이트합니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients/update' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'x-api-key: FA8VBTNpEzz871Neh0VI7wyxPwY_lhcPUotCbju-xOU' \
    -d '{
  "issuerInfo" : "도메인(https://api.profanity-filter.run), 연락처(010-9999-9999)",
  "note" : "업데이트된 메모입니다."
}'

Request

Name Description

Name	Description
`x-api-key`	클라이언트 API 키

x-api-key

클라이언트 API 키

{
  "issuerInfo" : "도메인(https://api.profanity-filter.run), 연락처(010-9999-9999)",
  "note" : "업데이트된 메모입니다."
}

Path Type Description

Path	Type	Description
`issuerInfo`	`String`	수정할 발급자 정보
`note`	`String`	수정할 메모

issuerInfo

String

수정할 발급자 정보

note

String

수정할 메모

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "id" : null,
    "email" : null,
    "issuerInfo" : "도메인(https://updated.com), 연락처(010-9999-9999)",
    "note" : "업데이트된 메모입니다.",
    "permissions" : null,
    "issuedAt" : null
  }
}

Path Type Description

Path	Type	Description
`data`	`Object`	수정된 클라이언트 정보
`data.id`	`Null`	클라이언트 ID
`data.email`	`Null`	클라이언트 이메일
`data.issuerInfo`	`String`	수정된 발급자 정보
`data.note`	`String`	수정된 메모
`data.permissions`	`Null`	권한 목록
`data.issuedAt`	`Null`	발급일시

data

Object

수정된 클라이언트 정보

data.id

Null

클라이언트 ID

data.email

Null

클라이언트 이메일

data.issuerInfo

String

수정된 발급자 정보

data.note

String

수정된 메모

data.permissions

Null

권한 목록

data.issuedAt

Null

발급일시

3.7. API Key 재 발급

발급된 API 키를 사용하여 API Key를 재 발급합니다.

해당 API는 추후 이메일 인증등 보안 강화 처리가 공지 없이 추가될 수 있습니다.

$ curl 'https://api.profanity-filter.run/api/v1/clients/reissue' -i -X POST \
    -H 'x-api-key: UreT8d3Wa66w5SpP_gMgEdvAHCPl-MiGUKngpJOobXs'

Request

Name Description

Name	Description
`x-api-key`	현재 API 키

x-api-key

현재 API 키

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "newApiKey" : "EIWToO3Yr7oVpiaBCbUs_0g7G7mu79P4pR1KkOnTy00"
  }
}

Path Type Description

Path	Type	Description
`data`	`Object`	재발급 결과
`data.newApiKey`	`String`	새로 발급된 API 키

data

Object

재발급 결과

data.newApiKey

String

새로 발급된 API 키

미 개발된 기능 중 필요한 API 가 있는 경우 연락 주시기 바랍니다.

4. 비속어 필터링

4.1. 필터링 요청

비속어 검사를 요청하는 API입니다,

$ curl 'https://api.profanity-filter.run/api/v1/filter' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'x-api-key: 2unWNa4FHDBXIAFpKg6v5zc45R2it0gnSK6C_55RSiw' \
    -d '{
  "text" : "욕설을 사용하지 ㅅㅂ 마세요.",
  "mode" : "FILTER",
  "callbackUrl" : null
}'

Request

클라이언트 등록 후 발급받은 API Key를 사용하여 비속어를 검사할 수 있습니다.

Name Description

Name	Description
`x-api-key`	클라이언트 API 키

x-api-key

클라이언트 API 키

{
  "text" : "욕설을 사용하지 ㅅㅂ 마세요.",
  "mode" : "FILTER",
  "callbackUrl" : null
}

Path Type Description

Path	Type	Description
`text`	`String`	필터링할 텍스트
`mode`	`String`	필터링 모드 (FILTER, DETECT)
`callbackUrl`	`Null`	콜백 URL (비동기 처리시 사용)

text

String

필터링할 텍스트

mode

String

필터링 모드 (FILTER, DETECT)

callbackUrl

Null

콜백 URL (비동기 처리시 사용)

해당 API 요청 시 사용할 수 있는 mode 의 종류는 다음과 같습니다.

코드 설명

코드	설명
`QUICK`	매우 원색적인 표현 , 비속어만 간략하게 검증할 수 있습니다.
`NORMAL`	데이터베이스에 있는 모든 비속어를 검증할 수 있습니다.
`FILTER`	제공된 문자열에 검출된 모든 비속어를 마스킹 처리합니다.

QUICK

매우 원색적인 표현 , 비속어만 간략하게 검증할 수 있습니다.

NORMAL

데이터베이스에 있는 모든 비속어를 검증할 수 있습니다.

FILTER

제공된 문자열에 검출된 모든 비속어를 마스킹 처리합니다.

Response

{
  "trackingId" : "9ed9abce-d588-489a-86ef-22ebc3576760",
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "detected" : [ {
    "length" : 2,
    "filteredWord" : "ㅅㅂ"
  } ],
  "filtered" : "욕설을 사용하지 ** 마세요.",
  "elapsed" : "0.00020948 s / 0.20948 ms / 209.480 µs"
}

Path Type Description

Path	Type	Description
`trackingId`	`String`	요청 식별자
`status`	`Object`	응답 상태 정보
`status.code`	`Number`	상태 코드
`status.message`	`String`	상태 메시지
`status.description`	`String`	상태 설명
`status.DetailDescription`	`String`	상세 설명
`detected[].length`	`Number`	필터링된 단어 길이
`detected[].filteredWord`	`String`	필터링된 단어
`filtered`	`String`	필터링된 결과 텍스트
`elapsed`	`String`	처리 소요 시간

trackingId

String

요청 식별자

status

Object

응답 상태 정보

status.code

Number

상태 코드

status.message

String

상태 메시지

status.description

String

상태 설명

status.DetailDescription

String

상세 설명

detected[].length

Number

필터링된 단어 길이

detected[].filteredWord

String

필터링된 단어

filtered

String

필터링된 결과 텍스트

elapsed

String

처리 소요 시간

elapsed 는 요청에 걸린 시간이 아닌 단어 탐색에 걸린 시간입니다.
비속어가 검출되지 않은 경우에는 empty array 가 반환됩니다.
비속어가 검출되었을 경우에는 해당 단어가 반환됩니다.
비속어가 검출되었을 경우에 Mode가 FILTER 일 경우 해당 단어가 마스킹 처리되어 반환됩니다.

5. 단어 요청

5.1. 추가 요청

단어의 추가/삭제/수정을 요청 할 수 있습니다.

$ curl 'https://api.profanity-filter.run/api/v1/word/request' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "word" : "새로운 단어",
  "reason" : "이 단어는 욕설입니다.",
  "severity" : "LOW",
  "type" : "ADD"
}'

Request

{
  "word" : "새로운 단어",
  "reason" : "이 단어는 욕설입니다.",
  "severity" : "LOW",
  "type" : "ADD"
}

Path Type Description

Path	Type	Description
`word`	`String`	신규 등록할 비속어
`reason`	`String`	신규 등록할 비속어의 이유
`severity`	`String`	신규 등록할 비속어의 심각도
`type`	`String`	요청 타입 (ADD, REMOVE, MODIFY)

word

String

신규 등록할 비속어

reason

String

신규 등록할 비속어의 이유

severity

String

신규 등록할 비속어의 심각도

type

String

요청 타입 (ADD, REMOVE, MODIFY)

해당 API 요청 시 사용할 수 있는 severity 의 종류는 다음과 같습니다.

코드 설명

코드	설명
`LOW`	낮은 수준의 중요도입니다.
`MEDIUM`	중간 수준의 중요도입니다.
`HIGH`	매운 높 수준의 중요도입니다.

LOW

낮은 수준의 중요도입니다.

MEDIUM

중간 수준의 중요도입니다.

HIGH

매운 높 수준의 중요도입니다.

해당 API 요청 시 사용할 수 있는 type 의 종류는 다음과 같습니다.

코드 설명

코드	설명
`ADD`	추가 요청입니다.
`REMOVE`	삭제 요청입니다.
`MODIFY`	수정 요청입니다.

ADD

추가 요청입니다.

REMOVE

삭제 요청입니다.

MODIFY

수정 요청입니다.

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "result" : true,
    "message" : "REQUEST_SUCCESS"
  }
}

Path Type Description

Path	Type	Description
`status`	`Object`	응답 상태 정보
`data`	`Object`	응답 데이터
`data.result`	`Boolean`	결과
`data.message`	`String`	결과 코드

status

Object

응답 상태 정보

data

Object

응답 데이터

data.result

Boolean

결과

data.message

String

결과 코드