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

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

1. overview(개요)

한국어 비속어를 모두 검증할 수 있는 서비스입니다.

운영은 제 개인 서버의 전기가 끊이지 않는 한 계속될 예정입니다.

만약 실제 운영 서비스에 사용할 목적이면서 비용에 대한 부담이 가능한 경우

[KISO 이용자 보호 시스템 API 서비스](https://www.safekiso.com/)를 사용해보세요.

월 7만원 가량의 비용으로 매우 높은 신뢰성을 가진 검증이 가능합니다.

다만 우리는 돈이 없지만 비속어는 막고 싶으니 제가 무료 서비스를 제공해보도록 하겠습니다.

1.1. History(업데이트 내역)

  • 진행예정 욕설 임베딩을 통한 유사도 비율 추산 기능 추가

  • 진행예정 open ai를 통한 요청한 신규 비속어 데이터 추가 자동화

  • 2025-02-15 자동 데이터베이스 신규 동기화 기능 개발

  • 2025-02-10 적절하기 않은 비속어 혹은 비속어 추가를 위한 API 개발

  • 2025-01-31 동일한 비속어 캐싱 처리 개선

  • 2025-01-25 API Key 기반의 인증 방식 적용

  • 2025-01-3 API Key 기반의 인증 방식 개발

  • 2024-12-30 특수문자를 고려한 검증 로직 개발 적용

  • 2024-12-27 순수한 아키텍처 개선을 목적으로 코드 리팩토링 진행

  • 2024-11-30 서버 컴퓨터 물리적 이동으로 인한 서버 검증 및 재배포

  • 2024-07-06 120+a 가량의 비속어 데이터베이스 추가

  • 2024-07-01 500+a 가량의 비속어 데이터베이스 추가

  • 2024.06 ~ 현재 서비스 운영 시작

1.2. Note

  • 정규식과 비속어 데이터베이스를 이용한 경량형 비속어 필터링 모델입니다.

  • 비속어 검사의 경우 `아호코라식 알고리즘`을 사용하여 빠르게 검사합니다.

  • 원색적인 욕설의 경우 대부분 필터링이 가능합니다.

  • [KISO 이용자 보호 시스템 API 서비스](https://www.safekiso.com/)의 스펙과 유사하게 구현되어 있습니다.

  • 영어 욕설의 경우 몇몇 단어들은 포함되어있지만 모든 단어가 포함되어있지는 않습니다. 추가적인 단어를 추가하고 싶으시면 이슈를 등록해주세요.

2. 클라이언트

2.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

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

status

Object

응답 상태 정보

data

Object

응답 데이터

data.name

String

등록된 클라이언트 이름

data.email

String

등록된 클라이언트 이메일

data.apiKey

String

발급된 API 키

data.note

String

등록된 메모

2.2. 정보확인

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

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

Request

Name Description

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

status

Object

응답 상태 정보

data.id

String

클라이언트 식별자

data.email

String

클라이언트 이메일

data.issuerInfo

String

클라이언트 발급 정보

data.note

String

클라이언트 메모

data.permissions

Array

권한 목록

data.issuedAt

String

발급일

2.3. 이메일 인증 코드 발송

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

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

Request

Parameter Description

email

이메일 주소

Response

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

data

String

전송 결과

2.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

email

String

이메일 주소

code

String

인증 코드

Response

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

data

Object

인증 결과

data.apikey

String

해당 이메일로 발급된 API 키

2.5. 클라이언트 폐기

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

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

Request

Name Description

x-api-key

클라이언트 API 키

Response

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

data

Boolean

폐기 성공 여부

2.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: ZfEvBqtFXbXiEjQChkLLTDn1qFjj1J8Be9DZbV2QjTQ' \
    -d '{
  "issuerInfo" : "도메인(https://api.profanity-filter.run), 연락처(010-9999-9999)",
  "note" : "업데이트된 메모입니다."
}'

Request

Name Description

x-api-key

클라이언트 API 키

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

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

data

Object

수정된 클라이언트 정보

data.id

Null

클라이언트 ID

data.email

Null

클라이언트 이메일

data.issuerInfo

String

수정된 발급자 정보

data.note

String

수정된 메모

data.permissions

Null

권한 목록

data.issuedAt

Null

발급일시

2.7. API Key 재 발급

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

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

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

Request

Name Description

x-api-key

현재 API 키

Response

{
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "data" : {
    "newApiKey" : "-4At_NUvJKUqlj3KPOfPsZgUZ4Hl1zZTLOEtPPjWgkc"
  }
}
Path Type Description

data

Object

재발급 결과

data.newApiKey

String

새로 발급된 API 키

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

3. 비속어 필터링

3.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: H9mh-uBwXgfS0xw6X8nSX5ytZLbjdi51n8eUBE_J6us' \
    -d '{
  "text" : "욕설을 사용하지 ㅅㅂ 마세요.",
  "mode" : "FILTER",
  "callbackUrl" : null
}'

Request

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

Name Description

x-api-key

클라이언트 API 키

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

text

String

필터링할 텍스트

mode

String

필터링 모드 (FILTER, DETECT)

callbackUrl

Null

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

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

코드 설명

QUICK

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

NORMAL

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

FILTER

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

Response

{
  "trackingId" : "03de6eee-6a8d-422b-a84a-97f7372ba657",
  "status" : {
    "code" : 2000,
    "message" : "Ok",
    "description" : "정상적으로 처리 되었습니다.",
    "DetailDescription" : ""
  },
  "detected" : [ {
    "length" : 2,
    "filteredWord" : "ㅅㅂ"
  } ],
  "filtered" : "욕설을 사용하지 ** 마세요.",
  "elapsed" : "0.00022461 s / 0.22461 ms / 224.611 µs"
}
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

처리 소요 시간

  • elapsed 는 요청에 걸린 시간이 아닌 단어 탐색에 걸린 시간입니다.

  • 비속어가 검출되지 않은 경우에는 empty array 가 반환됩니다.

  • 비속어가 검출되었을 경우에는 해당 단어가 반환됩니다.

  • 비속어가 검출되었을 경우에 Mode가 FILTER 일 경우 해당 단어가 마스킹 처리되어 반환됩니다.

4. 단어 요청

4.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

word

String

신규 등록할 비속어

reason

String

신규 등록할 비속어의 이유

severity

String

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

type

String

요청 타입 (ADD, REMOVE, MODIFY)

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

코드 설명

LOW

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

MEDIUM

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

HIGH

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

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

코드 설명

ADD

추가 요청입니다.

REMOVE

삭제 요청입니다.

MODIFY

수정 요청입니다.

Response

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

status

Object

응답 상태 정보

data

Object

응답 데이터

data.result

Boolean

결과

data.message

String

결과 코드