API Helpjuice v3
Dokumentacija o korištenju Helpjuice.com API V3 (JSON API)
Written by Emir Vatric
Updated at November 18th, 2020
Pregled
Verzija 3 API-ja Helpjuice strukturirana je oko REST, HTTP i JSON. URL-ovi krajnjih točaka API-ja organizirani su oko resursa, poput korisnika ili članaka. Koristi HTTP metode za navođenje radnje na resursu i HTTP kodove statusa za izražavanje statua grešaka. Resursi su predstavljeni u JSON-u slijedeći konvencionalnu shemu.
Osnovni URL
API-ju se pristupa pomoću osnovnog URL-a koji je specifičan za vaš račun. U primjerima navedenim u ovoj dokumentaciji koristimo URL vašeime računa. helpjuice .com kao helpjuice za URL vašeg stvarnog API računa. Pored toga, URL staze trebaju započeti s api / v3 da bi se odredila verzija 3 API-ja. Generalno, URL će biti u obliku:
https: // <vaš račun>. helpjuice .com / api / v3 / <resurs>.
Autentifikacija
Svi zahtjevi za API su autentificirani davanjem vašeg API ključa. API ključ treba pružiti kao HTTP zaglavlje s imenom Autorizacija ili kao parametar upita api_key . ( Kako mogu dobiti svoj API ključ ).
Ne zaboravite tajiti svoj API ključ. Ne dijelite ga i pazite da ga javno ne izlažete kodu klijenta.
| Zaglavlja | Params |
|---|---|
| Autorizacija | api_key |
| ffb722a62e8 ********************** | ffb722a62e8 ********************** |
Vaš API ključ možete pronaći na svom računu na stranici Postavke / API vjerodajnice za upute. Molimo posjetite Kako mogu dobiti svoj API ključ . Svaki račun ima svoj jedinstveni API ključ.
Zahtijevati token za API? opcija na stranici s postavkama vjerodajnica za API mora biti omogućena.
HTTP metode
API v3 koristi standardne HTTP metode za navođenje radnje na resursu.
| Metoda | Akcija |
|---|---|
| GET | Dohvatite resurs |
| POŠTA | Stvorite novi resurs |
| STAVITI | Ažurirajte resurs |
| IZBRIŠI | Uklonite resurs |
Shema
Svi API zahtjevi i tijela odgovora pridržavaju se zajedničkog JSON formata koji predstavlja pojedinačne stavke i kolekcije stavki .
Pojedinačni resursi
Pojedinačne resurse predstavlja član najvišeg nivoa nazvan prema resursu u obliku jednine. Ispod je prikaz jednog kontakta. Ovo bi se moglo koristiti u tijelu zahtjeva za PUT i to je ono što bi se vratilo u tijelu zahtjeva za GET.
{
"korisnik": {
"email": "jsmith@example.com",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"role_id": "superadmin",
"created_at": "2020-07-08T13: 50: 20.949Z",
"updated_at": "2020-07-08T13: 50: 20.949Z"
}
}Kolekcije
Zbirke resursa predstavlja član najvišeg nivoa nazvan prema resursu u množini. Ispod je prikaz kolekcije kontakata.
{
"korisnici": [
{
"email": "jsmith@example.com",
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"role_id": "superadmin",
"created_at": "2020-07-08T13: 50: 20.949Z",
"updated_at": "2020-07-08T13: 50: 20.949Z"
},
{
"email": "jdoe@example.com",
"name": "John Doe",
"first_name": "John",
"last_name": "Srna",
"role_id": "admin",
"created_at": "2020-07-08T13: 50: 20.949Z",
"updated_at": "2020-07-08T13: 50: 20.949Z"
}
]
}Paginacija
Krajnje točke koje vraćaju zbirke resursa moraju ograničiti broj zapisa vraćenih u danom odgovoru. Tipična krajnja točka zadano će vratiti 25 zapisa, ograničenje parametra upita može se koristiti za promjenu broja vraćenih zapisa.
{
"meta": {
"trenutno": 1,
"limit": 15,
"total_pages": 4,
"ukupan_broj": 50
}
}| Parametar | Opis |
|---|---|
| Limit | Broj rezultata za prikaz na svakoj stranici (zadano = 25, maks. = 1000). |
| Page | Trenutna stranica sa podacima. |
Greške
API koristi HTTP statusne kodove da naznači da je došlo do greške prilikom obrade zahtjeva. Postoje četiri glavne šifre statusa greške koje koristi API:
| Kod | Opis |
|---|---|
| 403 | U slučaju da API ključ nije osiguran. |
| 404 | U slučaju da traženi podaci ne postoje. |
| 422 | Zahtjev se nije mogao obraditi, obično zbog nedostajućeg ili nevaljanog parametra. |
U slučaju 422 pogreške, odgovor će također sadržavati objekt pogreške s objašnjenjem polja koja nedostaju ili su nevaljana. Evo primjera:
HTTP / 1.1 422 Neobradivi entitet
{
"greške": [
{
"email": "nije valjan."
}
]
}Pretraži
Pretražite bazu znanja
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / search? query = < helpjuice upit>
ODGOVOR sirov
{
"pretraživanja": [
{
"id": 1,
"name": "Članak Helpjuice",
"puž": "111- helpjuice sok-članak",
"tag_names": [],
"answer_sample": "Kratki odgovor u nekoliko riječi",
"long_answer_sample": "Duži odgovor, ali ne i cijeli članak",
"kategorije": {
"trenutno": {
"id": 23,
"name": "Korištenje Helpjuice",
"url": "URL u vašu kategoriju"
}
},
"last_published_date": "30. srpnja 2020",
"last_published_user_name": "John Doe",
"is_published": tačno,
"is_internal": netačno,
"url": "URL vašeg članka"
}
]
}
Korisnici
Kreirajte novog korisnika
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / korisnici
TIJELO sirovo
{
"korisnik": {
"first_name": "John",
"last_name": "Srna",
"email": "jhon@doe.com",
"role_id": "admin",
"group_ids": [1, 2]
}
}
| Polje | Tip | Opis |
|---|---|---|
| first_name * | String | Ime korisnika. |
| prezime | String | Prezime korisnika. |
| email * | String | Jedinstvena e-adresa korisnika. |
| role_id * | String | Uloga korisnika (superadmin, admin, saradnik, nacrt_pisaca, pregledač) |
| group_ids | Array | ID-ovi grupa u kojima se korisnik treba pridružiti. |
Ažurirajte korisnika
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
TIJELO sirovo
{
"korisnik": {
"first_name": "John"
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime | String | Ime korisnika. |
| prezime | String | Prezime korisnika. |
| String | Jedinstvena e-adresa korisnika. | |
| role_id | String | Uloga korisnika (superadmin, admin, saradnik, nacrt_pisaca, pregledač) |
| group_ids | Array | ID-ovi grupa u kojima se korisnik treba pridružiti. |
Dohvatite korisnika
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
TIJELO sirovo
{
"korisnik": {
"first_name": "John",
"last_name": "Srna",
"email": "john@doe.com",
"role_id": "admin"
}
}
Preuzimanje svih korisnika
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / korisnici
TIJELO sirovo
{
"korisnici": [
{
"email": "jsmith@example.com",
"firstName": "John",
"lastName": "Smith"
},
{
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Jones"
}
]
}
Izbrišite korisnika
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / users /: id
Grupe
Kreirajte novu grupu
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / grupe
TIJELO sirovo
{
"grupa": {
"name": "Nova grupa",
"smart_load": tačno,
"user_ids": [1, 2],
"auto_groups": "@ gmail.com, @ email.com",
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime * | String | Ime grupe. |
| smart_load | Boolean | Omogućite korisnike pametnog učitavanja u ovoj grupi. |
| user_ids | Array | Pridružite korisnike ovoj grupi. |
| auto_groups | String | Niz ekstenzija e-pošte odvojen zarezom koji će se automatski učitati u ovu grupu. smart_load mora biti omogućen. |
Ažurirajte grupu
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{
"grupa": {
"smart_load": tačno,
"auto_groups": "@ email.com"
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime | String | Ime grupe. |
| smart_load | Boolean | Omogućite korisnike pametnog učitavanja u ovoj grupi. |
| user_ids | Array | Pridružite korisnike ovoj grupi. |
| auto_groups | String | Niz ekstenzija e-pošte odvojen zarezom koji će se automatski učitati u ovu grupu. smart_load mora biti omogućen. |
Dohvatite grupu
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{
"grupa": {
"id": 1,
"name": "nova grupa",
"smart_load": tačno,
"created_at": "2020-07-29T09: 37: 03.529Z",
"auto_groups": [
{
"izraz": "@ gmail.com"
},
{
"expression": "@ email.com"
}
],
"korisnici": [
{
"id": 1,
"name": "John Doe",
"role_id": "superadmin",
},
{
"id": 2,
"name": "John Best",
"role_id": "admin",
}
]
}
}
Dohvati sve grupe
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / grupe
TIJELO sirovo
{
"grupe": [
{
"id": 2,
"name": "druga grupa",
"smart_load": netačno,
"created_at": "2020-07-29T09: 37: 03.529Z",
"auto_groups": [],
"korisnici": [
{
"id": 1,
"name": "Jhon Doe",
"role_id": "superadmin",
},
{
"id": 2,
"name": "Jhon Best",
"role_id": "admin",
}
]
},
{
"id": 3,
"name": "nova grupa",
"smart_load": netačno,
"created_at": "2020-07-29T09: 37: 03.529Z",
"auto_groups": [
{
"expression": "@ gamil.com"
}
],
"korisnici": [
{
"id": 1,
"name": "Jhon Doe",
"role_id": "superadmin",
},
{
"id": 2,
"name": "Jhon Best",
"role_id": "admin",
}
]
}
]
}
Izbrišite grupu
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / groups /: id
TIJELO sirovo
{
"grupa": {
"delete_users": netačno
}
}
| Polje | Tip | Opis |
|---|---|---|
| delete_users | Boolean | Izbrišite korisnike koji su unutar ove grupe. |
Kategorije
Kreirajte novu kategoriju
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / kategorije
TIJELO sirovo
{
"kategorija": {
"parent_id": 1,
"pristupačnost": 1,
"description": "Moja kategorija Helpjuice",
"name": "Kategorija",
"codename": "kategorija",
"arhivirano": false,
"user_ids": [1,2],
"group_ids": [1]
}
}
| Polje | Tip | Opis |
|---|---|---|
| parent_id | Ceo broj | ID nadređene kategorije. |
| pristupačnost | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničio je pristup člancima iznutra. |
| opis | String | Opis kategorije. |
| ime * | String | Naziv kategorije. |
| kodno ime | String | Puž za kategoriju. |
| arhivirano | Boolean | Bez obzira da li je kategorija arhivirana ili ne. |
| user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
| group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
Ažurirajte kategoriju
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
TIJELO sirovo
{
"kategorija": {
"name": "Nova kategorija"
}
}
| Polje | Tip | Opis |
|---|---|---|
| parent_id | Ceo broj | ID nadređene kategorije. |
| pristupačnost | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničio je pristup člancima iznutra. |
| opis | String | Opis kategorije. |
| ime | String | Naziv kategorije. |
| kodno ime | String | Puž za kategoriju. |
| arhivirano | Boolean | Bez obzira da li je kategorija arhivirana ili ne. |
| user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
| group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
Dohvatite kategoriju
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
TIJELO sirovo
{
"kategorija": {
"id": 1,
"name": "Naziv kategorije",
"kodno ime": "111-kategorija",
"pristupačnost": 0,
"description": "Opis",
"published_questions": [
{
"id": 22,
"name": "Objavljeni članak",
"url": "URL vašeg članka"
}
],
"draft_questions": [
{
"id": 23,
"name": "Nacrt članka",
"url": "URL vašeg članka"
}
],
"url": "URL u vašu kategoriju"
}
}
Dohvaćanje svih kategorija
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / kategorije
TIJELO sirovo
{
"kategorije": [
{
"id": 5,
"name": "Kategorija",
"codename": "22-kategorija",
"pristupačnost": 0,
"description": "Opis",
"published_questions": [
{
"id": 22,
"name": "Objavljeni članak",
"url": "URL vašeg članka"
}
],
"draft_questions": [
{
"id": 23,
"name": "Nacrt članka",
"url": "URL vašeg članka"
}
],
"url": "URL u vašu kategoriju"
},
{
"id": 55,
"name": "Kategorija",
"codename": "55-kategorija",
"pristupačnost": 0,
"description": "Opis",
"published_questions": [
{
"id": 22,
"name": "Objavljeni članak",
"url": "URL vašeg članka"
}
],
"draft_questions": [
{
"id": 23,
"name": "Nacrt članka",
"url": "URL vašeg članka"
}
],
"url": "URL u vašu kategoriju"
}
]
}
Izbrišite kategoriju
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / categories /: id
Članci
Napravite članak
Da bismo kreirali novi članak, potrebno je poslati samo ID nadređene kategorije, a mi ćemo stvoriti novi nacrt članka za vas.
URL
POST https: // <vaš račun>. helpjuice .com / api / v3 / articles
TIJELO sirovo
{
"članak": {
"name": "novi članak",
"description": "Ovo je novi članak",
"codename": "novi članak",
"visibility_id": 0,
"body": "<p> ovo je članak članka </p>",
"objavljeno": istina,
"id_kategorije": [1,2],
"user_ids": [1,2,6],
"group_ids": [1],
"contributor_user_ids": [1,2],
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime * | String | Naziv članka. |
| opis | String | Opis članka. |
| kodno ime | String | puž ili URL članka. |
| vidljivost_id | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničeni pristup članku. |
| tijelo | String | Tekst članka. |
| objavljeno | Boolean | Da li je članak objavljen ili ne. |
| id_kategorije | Array | Kategorije u kojima će se članak pojaviti. |
| user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
| group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
| contributor_user_ids | Array | Članovi koji doprinose članku |
Ažurirajte članak
URL
STAVITE https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
TIJELO sirovo
{
"članak": {
"name": "novi članak",
"codename": "novi članak"
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime | String | Naziv članka. |
| opis | String | Opis članka. |
| kodno ime | String | puž ili URL članka. |
| vidljivost_id | Ceo broj | (javno: 0, interno: 1, privatno: 2) ograničeni pristup članku. |
| tijelo | String | Tekst članka. |
| objavljeno | Boolean | Da li je članak objavljen ili ne. |
| id_kategorije | Array | Kategorije u kojima će se članak pojaviti. |
| user_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi će korisnici imati pristup njoj. |
| group_ids | Array | Ako je pristupačnost postavljena na privatnu, ovi članovi grupe imat će pristup. |
| contributor_user_ids | Array | Članovi koji doprinose članku |
Dohvatite članak
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
TIJELO sirovo
{
"članak": {
"id": 1,
"name": "Novi članak",
"prikazi": 112,
"pristupačnost": 0,
"description": "moj novi članak",
"codename": "novi članak",
"created_at": "2020-07-29T09: 37: 03.529Z",
"updated_at": "2020-07-29T09: 37: 03.529Z",
"objavljeno": netačno,
"odgovor": [
{
"body": "<p> Novi članak </p>",
"body_txt": "Novi članak",
"format": "html",
"updated_at": "2020-07-29T09: 37: 03.529Z"
}
],
"url": "URL vašeg članka"
}
}
Dohvatite sve članke
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / articles
TIJELO sirovo
{
"članci": [
{
"id": 1,
"name": "Novi članak",
"prikazi": 112,
"pristupačnost": 0,
"description": "moj novi članak",
"codename": "novi članak",
"created_at": "2020-07-29T09: 37: 03.529Z",
"updated_at": "2020-07-29T09: 37: 03.529Z",
"objavljeno": netačno,
"odgovor": [
{
"body": "<p> Novi članak </p>",
"body_txt": "Novi članak",
"format": "html",
"updated_at": "2020-07-29T09: 37: 03.529Z"
}
],
"url": "URL vašeg članka"
},
{
"id": 2,
"name": "Drugi članak",
"prikazi": 12,
"pristupačnost": 0,
"description": "moj drugi članak",
"codename": "drugi članak",
"created_at": "2020-07-29T09: 37: 03.529Z",
"updated_at": "2020-07-29T09: 37: 03.529Z",
"objavljeno": istina,
"odgovor": [
{
"body": "<p> Moj drugi članak </p>",
"body_txt": "Moj drugi članak",
"format": "html",
"updated_at": "2020-07-29T09: 37: 03.529Z"
}
],
"url": "URL vašeg članka"
}
]
}
Izbrišite članak
URL
OBRIŠI https: // <vaš račun>. helpjuice .com / api / v3 / articles /: id
Aktivnosti
Dohvatite aktivnost
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / activities /: id
ODGOVOR sirov
{
"aktivnost": {
"id": 1,
"trackable_id": 22,
"trackable_type": "Pitanje",
"owner_id": 1,
"action": "kreiraj",
"created_at": "2020-07-29T09: 37: 03.529Z"
}
}
Dohvatite sve aktivnosti
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / aktivnosti
ODGOVOR sirov
{
"članci": [
{
"id": 1,
"trackable_id": 22,
"trackable_type": "Pitanje",
"owner_id": 1,
"action": "kreiraj",
"created_at": "2020-07-29T09: 37: 03.529Z"
},
{
"id": 2,
"trackable_id": 22,
"trackable_type": "Pitanje",
"owner_id": 1,
"action": "kreiraj",
"created_at": "2020-07-29T09: 37: 03.529Z"
}
]
}
Postavke
Dohvatite postavke računa
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / settings / account
ODGOVOR sirov
{
"račun": {
"name": "Vaš račun",
"poddomena": "vaš_račun",
"internal_kb": netačno,
"expire_password_after_days": null,
"contact_us_email": "support.youraccount.com",
"contact_us_subject": "[Podrška] {{question.name}}",
"contact_us_single_sender": netačno,
"only_internal_article_requests": false,
"created_at": "2020-07-29T09: 37: 03.529Z"
}
}
Ažurirajte postavke računa
URL
DOBIJTE https: // <vaš račun>. helpjuice .com / api / v3 / postavke
ODGOVOR sirov
{
"postavke": {
"name": "Vaš račun",
"poddomena": "vaš_račun",
"internal_kb": netačno,
"expire_password_after_days": null,
"contact_us_email": "support.youraccount.com",
"contact_us_subject": "[Podrška] {{question.name}}",
"contact_us_single_sender": netačno,
"only_internal_article_requests": false,
"created_at": "2020-07-29T09: 37: 03.529Z"
}
}
| Polje | Tip | Opis |
|---|---|---|
| ime | String | Ime vašeg računa. |
| top_questions_count | Ceo broj | Broj članaka koji će biti prikazan u vašoj kb. |
| internal_kb | Boolean | Kb koristite samo interno. |
| expire_password_after_days | Ceo broj | Istek lozinke za nove korisnike, broj dana. |
| contact_us_email | String | Adresa e-pošte za podršku. |
| contact_us_subject | String | Obratite nam se e-mailom, naslov. |
| contact_us_single_sender | Boolean | Pošaljite sve e-poruke s kontaktima u polje contact_us_email. |
| only_internal_article_requests | Boolean | Samo prijavljeni korisnici mogu slati zahtjeve za članke. |