What is the correct way to work with custom data in the API?
As of CiviCRM 4.6, the api explorer is like 1-stop-shopping for browsing, building and testing api calls.


You can start on the "Examples" tab to see how custom values are generally done:

If you want more detailed explanation of how it works, try the "Code Docs" tab:

And finally, the Explorer tab lets you browse available params and will write the php/javascript/rest/cli code for you: