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.
This overview should arm you with enough information to get started using REST APIs. Again, I strongly encourage you to check out the in-depth tutorial at rest.elkstein.org. Or if you just want to dive right in, there's excellent sample code available for many REST APIs. An easy way to get started is to work through the tutorials or get the example code functioning in your environment, then move on from there.
Once you're comfortable with REST APIs, they are a great way to add integration between your application and existing Web services. REST APIs not only share a consistent interface, but they invariably rely on HTTP; after you've used one, you're in great shape to try out others. REST's consistency and openness make it one of the easiest API types to work with. With the ability to inspect the traffic between the client and the server, developing and debugging REST integrations is made that much easier.
This article, "How-to: REST Web services demystified," originally appeared at InfoWorld.com. Follow the latest news in programming at InfoWorld.com. For the latest business technology news, follow InfoWorld.com on Twitter.