Nu cred că este o coincidenţă faptul că Atlassian JIRA este tool-ul folosit pentru issue tracking în toate proiectele la care am luat parte până acum. Deşi există destul de multe produse de genul acesta pe piaţă, JIRA este unul dintre numele recunoscute de majoritatea actorilor implicaţi în proiecte informatice. Alături de alte titluri sonore precum Bugzilla sau Redmine, JIRA iese în evidenţă prin setul complet de funcţionalităţi, calitate, uşurinţa utilizării, dar şi prin extensibilitatea sa.
Atlassian JIRA a fost conceput ca un produs flexibil, uşor extensibil prin intermediul plugin-urilor. De asemenea, sistemul comunică cu lumea exterioară printr-o interfaţă REST, prin intermediul căreia clienţii platformei pot efectua diverse operaţii. În rândurile care urmează ne vom concentra atenţia asupra trăsăturilor acestui API, discutând câteva use case-uri clasice, cum ar fi căutarea unui issue sau adăugarea unui comentariu. De asemenea, vom petrece puţin timp uitându-ne atât la clientul Java pus la dispoziţie de Atlassian, cât şi la implementarea unui client REST utilizând Jersey, implementarea de referinţă de la Oracle.
Atlassian ne pune la dispoziţie o bibliotecă de clase menită să ne înlesnească lucrul cu API-ul REST, aceasta numindu-se sugestiv JIRA REST Java Client. Această bibliotecă expune la rândul său un API aproape complet pentru operațiile pe care le putem face într-un proiect JIRA. Spre exemplu, prin intermediul acestui client avem posibilitatea să găsim un anume proiect după cheie, să creăm tichete, să le ştergem, să adăugăm atașamente, să adăugăm worklog-uri și multe altele.
Metodele pe care le avem la dispoziție sunt grupate în mai multe clase, în funcție de obiectul business despre care este vorba. De exemplu, putem apela metodele ce țin de administrarea issue-urilor doar după ce obținem un obiect de tip IssueRestClient. Înainte de aceasta, avem nevoie de un obiect de tip JiraRestClient, creat prin intermediul unei implementări asincrone a interfeței JiraRestClientFactory.
Detaliile menționate mai sus pot fi observate în clasa JiraClient care face parte din proiectul demonstrativ ce însoțește acest articol. Proiectul poate fi descărcat de la adresa menționată în secțiunea Resurse. Trebuie să observăm faptul că acest proiect Java are scop didactic, codul sursă fiind unul minimal, care nu urmăreşte să respecte bunele practici.
Să presupunem că dorim să obținem cu ajutorul bibliotecii JRJC un obiect de tip Issue, ce modelează detaliile unui tichet JIRA. Acum că avem la dispoziție un obiect de tip JiraRestClient putem scrie următoarele:
Promise promise = jiraRestClient.getIssueClient().getIssue("JRA-9");
Issue issue = promise.claim(); Observăm că metoda getIssue(String issueKey) returnează un obiect de tip Promise, motiv pentru care, pentru a obține instanța Issue trebuie să apelăm metoda claim(). În aceeași manieră trebuie să procedăm și pentru obținerea altor obiecte, cum ar fi proiecte, worklogs etc. .
Unul dintre avantajele utilizării acestei biblioteci îl reprezintă faptul că nu trebuie să ne preocupăm de subtilitățile lucrului cu servicii REST. În fond, până în acest moment pentru noi a fost transparent faptul că avem de-a face cu un API REST. Pentru a ne face o părere mai clară despre ce înseamnă JIRA REST API, trebuie să realizăm propria noastră implementare a unui client REST, lucru pe care îl vom face utilizând Jersey.
Jersey ne oferă un mod simplu și rapid de a crea un client REST, aspect pe care îl ilustrăm în continuare:
String auth = new String(Base64.encode(USERNAME + ":" + PASSWORD));
Client client = Client.create();
WebResource webResource = client.resource(JIRA_SERVER + REST_PATH + query);
Builder builder = webResource.header("Authorization", "Basic " + auth)
.type(MediaType.APPLICATION_JSON).accept(MediaType.APPLICATION_JSON);Revenind la scenariul în care dorim să regăsim un tichet pe baza cheii, presupunem că parametrul query conține o cale de genul issue/JRA-9, unde JRA-9 este cheia tichetului. Pentru a obține obiectul Issue apelăm metoda get(), care corespunde metodei HTTP GET.
ClientResponse clientResponse = builder.get(ClientResponse.class);În acest moment putem obține obiectul JSON serializat, sub forma unui String:
String json = clientResponse.getEntity(String.class);Acest String poate fi apoi deserializat într-un bean creat de noi cu ajutorul bibliotecii Jackson, care ne pune la dispoziție diverse unelte de lucru cu JSON.
Acest scenariu este unul dintre cele mai simple, însă lucrurile devin mai complicate atunci când trebuie să creăm un worklog, spre exemplu. În acest caz, mai întâi trebuie să creăm un bean cu ajutorul căruia să modelăm un worklog și să populăm o instanță cu informațiile pe care dorim să le salvăm. Apoi trebuie să serializăm acest obiect sub forma unui String și să-l transmitem serviciului REST după modelul de mai sus, însă folosind metoda HTTP POST de data aceasta. Răspunsul serviciului va conține obiectul salvat sub formă serializată, îmbogățit cu noi informații, cum ar fi id-ul worklog-ului.
JIRA REST API este o interfață către lumea exterioară care are o valoare business incontestabilă. Acest API oferă organizațiilor posibilitatea să integreze cu ușurință tool-ul în ecosistemul propriu, pentru a defini procese dintre cele mai creative și complexe. Totuși, se poate observa că JIRA REST API nu acoperă în totalitate scenariile de utilizare JIRA. Unul dintre aspectele pentru care utilizatorii așteaptă o rezolvare îl reprezintă imposibilitatea de a lucra cu filtrele salvate. Există și un tichet pe acest subiect (JRA-36045), care încă este deschis.
Pe de altă parte, trebuie să menționăm că API-ul REST vine cu funcționalități importante, cum ar fi posibilitatea de a regăsi câmpurile custom și valorile acestora, operație pe care nu o puteam face cu API-ul SOAP.
JIRA REST API a ajuns la versiunea a doua şi, chiar dacă există loc de îmbunătăţiri, putem spune că este un produs matur, care vine cu funcţionalităţi importante față de predecesorul său.
de Ovidiu Mățan
