Utforska Planview AgilePlace API:er med Postman

Varje användare av Planview AgilePlace har tillgång till en mängd information genom att använda Planview AgilePlace Application Programming Interface (API). API:et kan användas för att extrahera statusinformation för en anpassad rapport, automatisera rutinuppgifter som att flytta eller uppdatera ett kort, synkronisera data med ett annat system och många andra användbara uppgifter.

Men om du aldrig har arbetat med ett API tidigare kan det vara lite överväldigande att komma igång. Tack och lov finns det bra verktyg som gör det lättare. I den här artikeln ska vi titta på ett av mina favoritverktyg för API:er, Postman.

Att få tag på en brevbärare

Om du har Google Chrome kan du få Postman som ett Chrome-tillägg. Om du har en Mac kan du få Postman som ett skrivbordsprogram . Jag förväntar mig att Postman kommer att släppa en Windows-applikation för skrivbord i framtiden.

När den är installerad bör du se skärmen för begäran om "Builder".

Gör din första API-förfrågan

I din första API-förfrågan hämtar vi en -lista över styrelser från ditt konto.

Ange webbadress och autentiseringsuppgifter för ditt konto

Ange webbadressen för begäran. I det här exemplet är webbadressen https://demoarea.leankit.com/kanban/api/boards. Vi måste ersätta demoarea med namnet på vårt Planview AgilePlace-konto.
Klicka på fliken Auktorisering om den inte redan är markerad.
Ändra "No Auth" till "Basic Auth".
Ange din e-postadress och ditt lösenord för kontot.
Klicka på knappen "Uppdatera begäran".

Uppdatera huvudet på begäran

Klicka på fliken Rubriker.
Lägg till två rubriker: Content-Type och Accept med värdet application/json.

Genom att ställa in Content-Type och Accept -huvudena kan API:et veta att alla data som vi skickar kommer att vara JavaScript Object Notation (JSON) och att alla data som returneras också ska vara i JSON-format.

Skicka in begäran

Vi är nu redo att göra en begäran! Klicka på knappen "Skicka". Så länge URL:n och kontoinformationen är korrekt bör vi se något som liknar följande bild.

Ett svar från API:et kommer nästan alltid att ha följande format:

Vi bör nu ha en lista över styrelser som innehåller varje styrelses Id, Title, Description, CreationDate (datum då styrelsen skapades) och annan grundläggande information.

Begär en enskild tavla

Nu när vi har en lista över styrelser kan vi använda Id för en styrelse för att få fram en enskild styrelse med alla dess detaljer, t.ex. användare, banor och kort.

Från listan över styrelser i föregående begäran kopierar vi Id för en styrelse. Uppdatera URL:en för begäran genom att i slutet lägga till ett snedstreck (/) och Id för den styrelse vi kopierade. Vår URL för begäran bör se ut ungefär så här: https://myaccount.leankit.com/kanban/api/boards/1234.
Klicka på knappen "Skicka".

Kollapsa block av data

Postman formaterar inte bara JSON-data för att göra den mer lättläst, utan gör det också enkelt att dela upp sektioner av data så att du kan fokusera på den information du bryr dig om. Klicka på pilen till vänster om du vill fälla ihop eller utöka block av data.

Spara begäran

En av de fina funktionerna i Postman är möjligheten att spara förfrågningar så att vi kan återanvända dem senare. Låt oss spara begäran för styrelsen så att vi inte behöver gå igenom alla dessa tidigare steg i framtiden.

Klicka på knappen Spara.
Välj en samling eller skapa en ny samling. En samling är som en mapp för att lagra dina begäranden. Vi kan skapa en ny samling genom att ange ett namn under "...eller skapa en ny samling".
Ange ett beskrivande namn för begäran.
Klicka på knappen "Lägg till i samlingen".

Sök efter kort

För vårt nästa trick ska vi söka efter kort.

Ändra begäranstypen från GET till POST.
Uppdatera URL:en för begäran genom att ändra myaccount till att matcha vårt kontonamn och 1234 till att matcha vårt forum-ID.
https://myaccount.leankit.com/kanban/api/board/1234/sökkort
Observera:/board/ i denna URL är singular i stället för plural, som i tidigare förfrågningar.
Klicka på fliken "Body" (kropp).
Välj kroppsformatet "raw".
Uppdatera kroppen med följande JSON:
{ "searchOptions": { "SearchTerm": "Försäljning", "Page": 1 } }
Obs: Ändra SearchTerm till vilken text som helst som matchar titeln eller beskrivningen av ett kort på din tavla. En lista över alla sök- och filteralternativ finns i dokumentationen för Search Cards.
Klicka på "Skicka" för att skicka begäran.

Sökresultat

Det är viktigt att påpeka att den JSON som returneras av kortet innehåller följande information.

Fastighet	värde
Totalt resultat	Det totala antalet kort som stämmer överens med sökningen.
Page	Den aktuella "sidan" eller de aktuella resultaten.
MaxResults	Det maximala antalet kort som returneras av sökningen.

Om antalet kort som matchar din sökning överstiger MaxResults, kommer dina resultat att delas upp i "sidor" som kräver separata förfrågningar.

Om vår sökning till exempel matchar 33 kort (" TotalResults": 33) kommer endast de första 20 korten att returneras. För att få de andra 13 korten måste vi ändra kroppen av begäran till följande och skicka den igen.

Hur man uppdaterar ett kort

I nästa exempel ska vi uppdatera ett kort. Vi kan ändra de flesta uppgifter på ett kort, t.ex. titel, beskrivning, planerat startdatum, planerat slutdatum och tilldelade användare, för att nämna några.

Vi måste åtminstone känna till kortets ID. Vi kan få detta ID på några olika sätt. Vi kan använda API:et för att hämta styrelsen eller söka efter kort, som i de tidigare exemplen, eller så kan vi hitta kort-ID:t på själva kortet i det nedre högra hörnet.

Därefter uppdaterar vi vår begäran.

Ändra begäranstypen till POST.
Uppdatera URL:en för begäran genom att ändra myaccount så att den matchar vårt kontonamn.
https://myaccount.leankit.com/kanban/api/card/update
Klicka på fliken "Body" (kropp).
Välj kroppsformatet "raw".
Uppdatera kroppen med följande JSON:
{ "CardId": 123456, "Title": "Uppdaterad med hjälp av API" }
Obs: Ändra värdet CardId så att det matchar ID:et för det kort du uppdaterar och Title till önskad text. Eller uppdatera ett annat fält. En lista över alla fält som kan uppdateras finns i dokumentationen Update Card.
Klicka på "Skicka" för att skicka begäran.

Om det lyckas kommer API-svaret att innehålla den uppdaterade kortinformationen.

Skrivet av Planview-bloggen

Planview-bloggen