Warcraft Wiki talk:How to edit API pages

I'm a bit new to WoWWiki and I'm finding this page a bit confusing. The introduction indicates that the use of Template:WoWAPI is obsolete yet the API boilerplate continues to use it. This seems counterproductive. It also mentions the use of breadcrumbs. I've seen no indication that any of the API entries actually have these. I've considered adding them as I make updates but the given example on how to do this isn't very clear. Also I've seen a "breadcrumb1" template used elsewhere that isn't mentioned in the breadcrumb page. Any clarification on all this would be helpful. -- morevit

The template that has been deprecated is {{WoW API}} (notice case and the space). The new one is {{wowapi}}. If they'd have been used in the same positions, this would have been a pointless change, but the old one is consistently used at the bottom of pages, while the new is meant to be used at the top of pages -- hence the different name. (Plus the new one is easier to get right since there's no case mixing =)) --Mikk 07:15, 13 July 2006 (EDT)

And .. hm.. breadcrumb? Where? There shouldn't be any in API pages. There might be ones in other pages, but AFAIK they should all be pulled in via the heading templates and not typed in manually. Unless I'm forgetting some category of pages. Do you have an example of where it's being confusing? --Mikk 07:18, 13 July 2006 (EDT)

Thanks for the clarification on the distinction between {{WoW API}} and {{wowapi}}. Not immediately obvious to the newcomer. I'll have to look into this.

As far as breadcrumbs go I was referring to the discussion of them at the top of this page. If they're implemented by the template then that's not an issue. -- morevit 09:55, 14 July 2006 (EDT)

Perhaps I'm still missing something here. I've looked at pages using the {{wowapi}} template. I'd expect to see something like:

Interface Customization >> World of Warcraft API >> Global Function Groups >> Action Functions >> ActionButtonDown

or perhaps just the truncated

Action Functions >> ActionButtonDown

at the top of the ActionButtonDown API page. -- --Morevit 07:59, 14 July 2006 (EDT)

Ah, yeah, those... We had a breadcrumb at the top for a short while, but it didn't include the categorization, so mostly just ended up duplicating the links available in the menu at the right. The problem with categorization is that about 100 of the APIs are categorized under more than one category. :-/   --Mikk 14:02, 14 July 2006 (EDT)

Right. The impression I got was that the move to add these was to aid in establishing primary categories for each method. --Morevit 09:55, 15 July 2006 (EDT)

Version tags

There seems to be a lack of guideline about how to actually mark new functions on the WoW API page. I stumbled across that when I wanted to add links to some of the new functions of WOW 5.0 to the list and couldn't find out what the proper way to add the corresponding version number is. At the moment there seem to be more than a dozen different ways to add version markers... Just to give a few examples:

• XXXX. (NEW 2.0.3)
• XXXX. (NEW in 3.2)
• XXXX -- added in 2.1
• XXXX. -- added in 4.3.0
• XXX New in 3.0.8
• XXXX. (3.3.3)
• XXXX -- added in 4.3.0 [referenced with link to wow.go-hero.net]
• XXXX (new in 2.4)
• XXXX - Added in 1.12
• XXXX. (New: 3.3.3)
• XXXX. (New in Patch 2.4) [link to patch 2.4]

Some differ in upper/lower case only, others add links, different separator styles being used, etc. How about putting up a guideline with ONE definition of how version markers should look like? I personally don't have any preference. But in order to get an somewhere with this situation I'd suggest to use the following style:
XXX. (NEW in x.x[.x]) [ x.x[.x] are optionally linked to the wowpedia-page for this particular patch]

This would lead to the following guidelines:

• a function description should end with a "." full-stop.
• if the function is known to have been added in a certain version in WoW it'd be suffixed with the version marker: (New in x.x[.x]).
• the version number is to be given in major/minor[/fix] version where the fix-version number is to be omitted, if it equals 0

  f.e. 5.0.4 -> 5.0.4
       4.1.0 -> 4.1
       2.0.0 -> 2.0

• if there is a wowpedia-page for the new patch, the version number should be linked to that page

Does this suggestion warrant a voting process? --Luke1410 (talk) 23:22, 2 September 2012 (UTC)

You're free to standardize them as you see fit. I would suggest simply removing the (NEW in X) tags from the pages containing lists of API functions once the relevant patch has been out for a month or so -- their main purpose is probably to avoid people thinking that API functions from the latest PTR/Beta patch are actually available for use on live realms. Those version numbers could still be reflected in a Patch Changes section on individual API pages. — foxlit (talk) 00:16, 3 September 2012 (UTC)

I feel that "NEW" is an incredibly bad term to use for what is supposed to be a permanent database. "added in x.y[.z]" is my recommendation, and I've changed the guidelines to reflect this. I don't have a problem with leaving (added in 1.10) on the page long after the patch's time has passed, but I don't particularly care either way.

As to format, I've tried to standardize it in the guidelines based on current and clear usage. The two main ones I see are the double hyphen with italics, and the parenthetical. (Now that I think about it they should probably both be italicized, but that's not very common at the moment.) It's a little silly having both but they work. I do think capitalization should be lowercase to minimize its importance next to the description, and I find the letter after a parenthesis more readable when it's lowercase. Links to the patch's entry on this site seem fine (and optional), but I see no reason to link offsite.

Descriptions should end with a period. It looks cleaner having a definite endpoint, especially when followed by a version number.

- Jerodast (talk) 09:14, 1 January 2014 (UTC)

Use of {{api}} template on main API page

While working on some individual function pages, I noticed foxlit's excellent use of the {{api}} template to avoid clunky [[API functionNameOhGodItsSoLong|functionNameOhGodItsSoLong]] wiki coding. However I notice that template is not in use on the main API page. Is there a reason for this? I mentioned {{api}} in the expanded guidelines I just put up, so feel free to remove it if necessary. Alternatively, I'll remove the clunky version from the guidelines entirely.

If there's no reason to use the clunky version on the main page, I'd undertake replacing the current usage with the sleeker one, but that's a discussion for that page's talk page.

- Jerodast (talk) 10:06, 1 January 2014 (UTC)

New API format

I'm working with User:Ddcorkum to update the relatively recent Blizzard-Documented API pages and I'll be changing the guidelines to reflect the new formatting. I've been using https://github.com/Ketho/WowpediaApiDoc to generate pages easier. Ketho (talk) 00:40, 7 May 2020 (UTC)