(Updated to highlight functionality added in
Patch 5.1.0 + Patch 5.2.0)
The PetJournal API as it appears in 5.0.4 is rather closely tailored to the Blizzard_PetJournal addon, and is not particularly nice to work with in other addons. Here are a couple of suggestions:
Add table = C_PetJournal.GetAllPetIDs([table])
Currently, the only way to figure out which pets are known to the player is to iterate using
C_PetJournal.GetPetInfoByIndex, which is affected by four separate PetJournal filter types. One of these filter types takes enumerated flags -- if you decided to add a new one tomorrow, addons would require code updates to get the unfiltered information they need. Saving and restoring these four filters is painful, but necessary to keep the Blizzard_PetJournal in a sane state after an addon is done with
GetPetInfoByIndex.
Add petID = C_PetJournal.GetPetIDBySpeciesID(speciesID)
This could be used to determine whether a player owns any pet of a particular species -- for instance, if an addon wants to display a button to summon a particular unique pet (e.g. Grunty).
Patch 5.1.0: Added
C_PetJournal.GetNumCollectedInfo.
Expose pet cooldowns
Some pets, like the Guild Herald, are still subject to a cooldown. PetJournal does not expose this information, and
GetSpellCooldown (with a correct spell ID that cannot currently be retrieved through the PetJournal API) can only be used if the player character already knew the pet before 5.0.4.
Patch 5.2.0: Added
C_PetJournal.GetPetCooldownByGUID.
Fix /cast Battle Pet Name, or add /summonpet Battle Pet Name
Pre-5.0.4, companions could be summoned using /cast and /castsequence commands, which could be used in a macro by ordinary players. Currently, the /cast commands fail with a non-intuitive error ("You do not have a pet") if you knew the pet 5.0.4 or fail silently if you didn't, and the only way to summon a pet is using
C_PetJournal.SummonPetByID(petID), which is non-trivial to use in a macro, as the
petID is player-specific.
Patch 5.1.0: Added
/summonpet Pet Name,
/randompet, and
/randomfavoritepet slash commands, backed by
C_PetJournal.FindPetIDByName and
C_PetJournal.SummonRandomPet API functions.
The API as a whole would be easier to work with if the filtering required by Blizzard_PetJournal was done in that addon's Lua code, rather than using C-side state that's shared between all addons, but it's probably too late to change that now.
Addon authors: End wrote LibPetJournal-2.0, a library that simplifies retrieving petIDs of known pets from the PetJournal, and provides a callback that fires when the available pets change, which may be useful if you're dealing with the PetJournal API in its present state.