API talk:Extensions

Make "this is about modules" more obvious

Today a developer tried to find this, to learn about writing API modules, and didn't see it. How can we make it more discoverable? Sumana Harihareswara, Wikimedia Foundation Volunteer Development Coordinator 01:27, 9 February 2012 (UTC)

• I agree, I couldn't find it! I added pointers to this in API:Implementation Strategy and Manual:Developing extensions. -- S Page (WMF) (talk) 04:13, 22 February 2014 (UTC)

How should an API return errors?

This doesn't explain how extensions should handle error cases in their API, it would be very helpful if it did. API:Errors and warnings says clients of extensions will get an error with code and info fields, but how do extensions return these?

ApiBase implements

• setWarning() function, seems to stack up warnings
• a dieUsage that seems relevant.

E.g. includes/api/ApiEmailUser.php calls $this->dieUsageMsg( ) for API failures while returning result of 'Success' or 'Failure' when it interprets a MW Status object. The function signature is

 public function dieUsage( $description, $errorCode, $httpRespCode = 0, $extradata = null );

In ApiBase there's a getPossibleErrors() function and some API providers return an array of 'code', 'info' pairs, is that related?

Also is there any namespacing of errorcode and info? Localization? Presumably code calling API's should show appropriately localized messages to the user according to the error's code

 $this->dieUsageMsg( wfMsg( 'my-error-string' ), my-error-code );

and the ; Are there default localized messages for the the predefined API error codes? -- User:S Page (WMF) 23:20, 24 October 2012 (UTC)

I added a bit of info here. Leucosticte (talk) 01:11, 25 October 2012 (UTC)

Definitely helps, thanks on behalf of all developers! -- S Page (WMF) (talk) 06:17, 25 October 2012 (UTC)

messages

I think the messages section needs to be updated to the new json format.--Physikerwelt (talk) 19:36, 13 May 2014 (UTC)

Extensions should use subpages instead of the API NS

I just addd a bit to this page about how extensions should put their API docs at Extension:ExtName/API, hope that's okay.

The only API namespace pages I could find that share the names of extensions are: Contributors, Info, Links, Purge, Random, and Review. The last of these was the only one that was actually about an extension, so I've moved it to Extension:FlaggedRevs/API.

Extensions that do follow the pattern are: Extension:CentralAuth/API; Extension:CodeReview/API; Extension:FlaggedRevs/API; Extension:GlobalBlocking/API; Extension:LiquidThreads/API; Extension:MassMessage/API; Extension:PageLanguageApi/API; Extension:SpamBlacklist/API; Extension:StructuredDiscussions/API; Extension:TimedMediaHandler/API; and Wikibase Repository (vers. 1, 2, 3, & 4).

@MaxSem: I was looking at this in part because I was wondering where we should put the docs for GlobalPreferences. —Sam Wilson 08:01, 28 June 2018 (UTC)

There was also API:Globalblocks etc, so I don't really know... I think however that API documentation can go to extensions' main pages unless they're too big. Max Semenik (talk) 20:21, 28 June 2018 (UTC)

Good point. That page API:Globalblocks contained info that was already part of Extension:GlobalBlocking/API so I've redirected it there. I can't find any others, so I reckon the rule stands. Sam Wilson 23:27, 28 June 2018 (UTC)