Merkit-API

Hallitse merkkipohjia — tunnisteita, joita myönnät vastaanottajille.

Kaikki päätepisteet vaativat todennuksen X-Api-Key-otsikon kautta. Katso Todennus.

Luo merkki

Luo uusi merkki varmennetun myöntäjän alle.

POST /badges

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
name	string	Kyllä	Merkin otsikko
description	string	Kyllä	Mitä merkki edustaa
criteria	string	Kyllä	Mitä vastaanottaja teki saadakseen tämän merkin
image	string	Kyllä	Base64-koodattu kuva (PNG tai JPG)
issuerId	string	Kyllä	Varmennetun myöntäjän ID

Esimerkki

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Vastaus

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
  }
}

Huomautuksia

• Myöntäjän on oltava varmennettu ennen merkkien luomista.
• Kuva ladataan IPFS:ään pysyvää tallennusta varten.

---

Listaa merkit

Hae kaikki luomasi merkit.

GET /badges

Esimerkki

curl -X GET https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here"

Vastaus

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
        "image": "https://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Päivitä merkki

Päivitä olemassa olevaa merkkiä. Vain antamasi kentät muuttuvat.

PUT /badges/{badgeId}

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Merkin ID (polun parametri)
name	string	Ei	Uusi merkin otsikko
description	string	Ei	Uusi kuvaus
criteria	string	Ei	Uudet kriteerit
image	string	Ei	Uusi base64-koodattu kuva

Esimerkki

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Vastaus

{
  "statusCode": 200,
  "info": {
    "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "updated": true
  }
}

---

Päivitä jakamisteksti

Aseta mukautettu teksti, joka näkyy, kun vastaanottajat jakavat tämän merkin sosiaalisessa mediassa.

PUT /badges/{badgeId}/share-text

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Merkin ID (polun parametri)
text	string	Kyllä	Jakamisteksti (HTML ei sallittu)

Esimerkki

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Vastaus

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

Poista merkki

Poista merkki. Merkillä ei saa olla myöntöjä.

DELETE /badges/{badgeId}

Esimerkki

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Vastaus

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Virheet

• 400 — merkillä on myöntöjä, eikä sitä voi poistaa
• 404 — merkkiä ei löydy