Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

How-to: REST Web services demystified

REST API integration needn't be daunting -- get started with web services

By Kirsten Jones, InfoWorld, 08/23/12

Page 4 of 5

• 400: Formatting error. Your headers, parameters, or POST body are not formatted correctly. You may be missing a required parameter or you have added an unexpected one. The response body should have information that will help you spot the misstep.
• 401: Authentication error. The server doesn't recognize something about the authentication you're using. Your signature may not match, or the token may be invalid. Again, check the response body for helpful clues. If you're lucky, the API team has made tools available that will allow you to check your authentication and work through the issue.
• 403: Authorization error. The server knows who you (and your user) are, but you aren't allowed to see the resource. Sometimes this is a permission issue (restricted to certain users). But if you start seeing 403 errors after successful requests of the same type, then most likely you're being throttled (so you're no longer allowed to access that resource). Review the throttle limits for the API, and remember that throttles are frequently different for an application as a whole as opposed to specific users of an application.
• 404: Not found. The resource you requested isn't a valid path. We all know what this means.

Asking good questions. Most APIs have documentation, forums, and other resources available to help you achieve success. However, if you're not able to solve the problem on your own, you'll want to ask for help on a forum -- either one devoted to the specific API or a good general-purpose developer's venue like StackOverflow. Technical questions asked without enough context can kick off a frustrating cycle of exploratory questions, guesses, and clarifications, delaying the resolution of your issue.

In general, you want to follow this kind of template:

• I did X.
• I expected Y to happen.
• To my dismay, Z happened instead.

All three pieces are critically important in a good question or bug report.

I did X. What exactly were you doing when the problem occurred? Can you consistently reproduce the problem? What else did you try? Be sure to give full context, including the language or libraries (or browser) you're using -- all the details a person starting from scratch might need to reproduce your problem. In the case of a REST API call, you'll need to include the URL, the headers, and the body of the request.

I expected Y to happen. Remember, it often happens that things are working just as intended, but your expectation doesn't match what the system is doing. This might mean the documentation needs improving or (just maybe) you haven't read the documentation closely enough. If you describe what you were expecting to happen, the API team or support community will better understand how to get you what you need. If you can point to the documentation you're following, so much the better.

To my dismay, Z happened instead. Did you get an error? Do you have the complete response? Provide all the headers, status code, and response body.

A good question provides support staff or the forum reader with enough context to answer the inquiry correctly the first time. Sure, it takes a little longer to craft questions with all the relevant detail, but you'll get a much quicker response and a faster resolution. Your goal is to give the reader everything they need to answer the question correctly the first time. It will save you -- as well as the support person -- both time and frustration.

For more enterprise computing news, visit InfoWorld. Story copyright InfoWorld Media Group, Inc.