API 예시

이 문서는 REST API를 사용한 구현 방법을 안내합니다.

Push Notification API

caution

⚠️ 만일 잘못된 user_id로 요청될 경우, 에러가 발생합니다. (문제 해결 링크)

토큰 등록

푸시 알림을 받을 사용자의 푸시 토큰을 등록하는 API입니다.

APNs, FCM으로부터 발급 받은 푸시 토큰이 필요합니다.

user_id는 각 서비스에서 사용자를 식별하기 위한 값을 보냅니다. 해당 값을 이용해 특정 앱에 등록된 유저의 토큰을 조회, 등록, 삭제할 수 있습니다.

기본 정보

POST /v1/push/token
HOST : api.maxst.com/noti
Content-Type : application/json
Authorization: Bearer {token}

Request

Name	Type	Description	Required
user_id	String	사용자 고유 ID	O
push_type	String	푸시 토큰 타입, ANDROID 혹은 IOS	O
push_token	String	APNs(64자), FCM으로부터 발급 받은 푸시 토큰	O

Response

HTTP/1.1 201 Created
Content-Length: 0
Location: /push/token/${PUSH_TOKEN}

Sample

Request

curl -X POST "https://api.maxst.com/noti/v1/push/token" \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
    "user_id": "${USER_ID}",
    "push_type": "ANDROID",
    "push_token": "${PUSH_TOKEN}"
    }'

Response

HTTP/1.1 201 Created
Location: /push/token/${PUSH_TOKEN}

토큰 조회

기본 정보

GET /v1/push/token
HOST : api.maxst.com/noti
Authorization: Bearer {token}

Parameter

Name	Type	Description	Required
user_id	String	사용자 고유 ID	O

PASSPORT 에 등록된 사용자의 푸시 토큰 정보를 조회하는 API입니다.

요청 시 user_id는 반드시 포함해야 합니다. 토큰이 등록되지 않은 유저의 경우 에러가 발생합니다.

요청 성공 시 응답은 JSON Array로 푸시 토큰 정보를 받습니다. 각 사용자에게 여러 개의 푸시 토큰이 등록될 수 있으므로 응답에는 복수의 토큰이 포함될 수 있습니다. 각 푸시 토큰 정보는 푸시 토큰의 종류와 값, 생성 일시를 포함합니다.

Response

Name	Type	Description
user_id	String	사용자 고유 ID
push_token	String	APNs(64자), FCM으로부터 발급 받은 푸시 토큰
push_type	String	푸시 토큰 타입, ANDROID 혹은 IOS
created_at	String	푸시 토큰을 처음 등록한 시각

토큰 조회 실패 시

• 에러 정보에 따라, 사용자에게 적절한 안내 문구를 표시하도록 처리합니다.

Sample

Request

curl -X GET "https://api.maxst.com/noti/v1/push/token?user_id=${USER_ID}" \
    -H "Authorization: Bearer {token}"

Response

{
    "user_id": ${USER_ID},
    "token_list": [
            {
                "push_token": ${PUSH_TOKEN},
                "push_type": "ANDROID",
                "created_at": "2023-06-30 09:09:15"
            }
    ]
}

토큰 삭제

특정 사용자의 푸시 토큰을 삭제하는 API입니다. 사용자가 로그아웃하거나 푸시 알림을 끄는 경우, 더 이상 푸시 알림이 보내지지 않도록 하기 위해 이 API를 사용합니다.

요청 시 파라미터로 user_id, push_token을 전달합니다.

토큰 삭제에 성공하면 HTTP 상태 코드 200 응답을 받으며 응답 본문은 없습니다.

기본 정보

DELETE /v1/push/token/${PUSH_TOKEN}
HOST api.maxst.com/noti
Authorization: Bearer {token}

Parameter

Name	Type	Description	Required
user_id	String	사용자 고유 ID	O
push_token	String	APNs(64자), FCM으로부터 발급 받은 푸시 토큰	O

Sample

Request

curl -X DELETE \
    -H "Authorization: Bearer {token}" \
    "https://api.maxst.com/noti/v1/push/token/${PUSH_TOKEN}?user_id=${USER_ID}" \

Response

HTTP/1.1 200 OK

푸시 알림 보내기

푸시 알림을 보내는 API입니다. 수신할 사용자의 user_id로 등록된 모든 기기에 푸시 알림이 보내집니다.

기본 정보

POST /v1/push/send
HOST api.maxst.com/noti
Authorization: Bearer {token}

Request

Name	Type	Description	Required
recipient_ids	List<String>	사용자 고유 ID의 목록.	O
push_type	String	전송할 푸시 타입, ANDROID, IOS	O
title	String	푸시 알림의 제목을 지정합니다.	O
body	String	푸시 알림의 본문 내용을 지정합니다.	O
data	Object	추가 데이터를 지정합니다. 푸시 알림이 전송될 때 함께 전달되는 추가 정보를 의미합니다.	X

Response

요청 결과를 확인할 수 있는 정보가 제공됩니다.

Name	Type	Description
recipient_id	String	사용자의 고유 ID
transaction_id	String	전송 결과를 확인할 수 있는 UUID
transaction_type	String	전송된 푸시 타입, ANDROID 혹은 IOS
status	String	요청 상태

Sample

Request

curl -X POST "https://api.maxst.com/noti/v1/push/send" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {token}" \
    -d '{
        "recipient_ids": [
            "${USER_ID}", "${USER_ID}"
        ],
        "push_type": "ANDROID",
        "title": "푸시 제목입니다.",
        "body": "푸시 내용입니다.",
        "data": {
            "key": "value"
        }
}'

Response

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8

{
    "transactions": [
        {
            "recipient_id": "${USER_ID}",
            "transaction_id": "${TRANSACTION_ID}",
            "transaction_type": "ANDROID",
            "status": "SUCCESS"
        }
    ]
}

푸시 결과 조회

푸시 알림 전송 결과를 조회할 수 있는 API 입니다.

기본 정보

GET /v1/push/transaction/${TRANSACTION_ID}
HOST api.maxst.com/noti

Parameter

Name	Type	Description	Required
transaction_id	String	푸시 전송 요청 후 응답으로 받은 UUID	O

Response

Name	Type	Description
recipient_id	String	수신한 사용자 고유 ID
transaction_id	String	전송 결과를 확인할 수 있는 UUID
transaction_at	String	해당 요청시 저장된 시각
status	String	요청 상태
request_id	String	전송 결과를 확인할 수 있는 message ID, 요청 실패 시 실패 메시지

Sample

Request

curl -X 'GET' "https://api.maxst.com/noti/v1/push/transaction/${TRANSACTION_ID}" \
-H "Content-Type: application/json" \

Response

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8

{
    "recipient_id": "${USER_ID}",
    "transaction_id": "${TRANSACTION_ID}",
    "transaction_at": "2023-06-29 16:08:57",
    "request_id": "${REQUEST_ID}",
    "status": "SUCCESS"
}

---