Märkide API viide: märkide loomine, kinnitamine ja pärimine

Halda märgimalle — tõendeid, mida sa saajatele välja annad.

Kui soovid selle märgi anda korraga paljudele saajatele CSV-faili üleslaadimisega, mitte API kaudu, vt Hulgitõendid.

Kõik otspunktid nõuavad autentimist päise X-Api-Key kaudu. Vt Autentimine.

Loo märk

Loo uus märk kinnitatud väljaandja alla.

POST /badges

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
name	string	Jah	Märgi pealkiri
description	string	Jah	Mida märk tähistab
criteria	string	Jah	Mida saaja selle märgi teenimiseks tegi
image	string	Jah	Base64-kodeeritud pilt (PNG või JPG)
issuerId	string	Jah	Kinnitatud väljaandja ID
shareText	string	Ei	Selle märgi vaikimisi sotsiaalmeedias jagamise tekst. Toetab kohahoidjaid , ja . Väljajätmisel kasutatakse sisseehitatud vaiketeksti.
designJson	string	Ei	Serialiseeritud märgidisaineri dokument, mis salvestatakse, et märki saaks hiljem kihthaaval uuesti muuta.

Näide

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"
    }
  }'

Vastus

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

Märkused

• Väljaandja peab olema kinnitatud, enne kui märke saab luua.
• Pilt salvestatakse Amazon S3-sse ja edastatakse meie ülemaailmse CDN-i kaudu muutumatu, sisupõhise URL-i alt.
• Kui märgiklass on olemas, anna see saajatele välja Tõendite API abil.

---

Märkide loend

Pärige kõik enda loodud märgid.

GET /badges

Näide

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

Vastus

[
  {
    "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://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Hangi märk

Pärige üksik märk koos selle jagamistekstiga ja serialiseeritud märgidisaineri dokumendiga (designJson). Seda otspunkti kasutab märgi muutmise aken üksikute kihtide taastamiseks; loendi otspunkt jätab designJson välja, et vastused püsiksid kerged.

GET /badges/{badgeId}

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
badgeId	string	Jah	Märgi ID (teeparameeter)

Näide

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

Vastus

{
  "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://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Jagamistekst on alati kaasatud. Kergem loendivariant GET /badges?badgeId={id} tagastab sama dokumendi ilma designJson-ita ning lisab jagamisteksti ainult siis, kui seda kutsutakse parameetriga includeShareText=true.

---

Uuenda märki

Uuenda olemasolevat märki. Muudetakse ainult need väljad, mille sa annad.

PUT /badges/{badgeId}

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
badgeId	string	Jah	Märgi ID (teeparameeter)
name	string	Ei	Märgi uus pealkiri
description	string	Ei	Uus kirjeldus
criteria	string	Ei	Uued kriteeriumid
image	string	Ei	Uus Base64-kodeeritud pilt
designJson	string	Ei	Uus serialiseeritud märgidisaineri dokument.

Näide

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"
    }
  }'

Vastus

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

---

Uuenda jagamisteksti

Määra kohandatud tekst, mida kuvatakse, kui saajad seda märki sotsiaalmeedias jagavad.

PUT /badges/{badgeId}/share-text

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
badgeId	string	Jah	Märgi ID (teeparameeter)
text	string	Jah	Jagamistekst (HTML ei ole lubatud)

Näide

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:"
    }
  }'

Vastus

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Kustuta märk

Kustuta märk. Märgil ei tohi olla tõendeid.

DELETE /badges/{badgeId}

Näide

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

Vastus

Tagastab lihtsa kinnitusstringi:

"badge has been deleted"

Vead

• 400 — märgil on endiselt väljaantud tõendeid: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — märki ei leitud