Solution for Chapter 6: Sketching APIs
The solution for the Chapter Exercise, is your first chance to actually sketch out what your API resources and responses will look like. The instructions are to start with the WSD diagram from the previous exercise (credit-check-diagram.png) and then create sketches of what the API would look like.
The first sketch is an HTML sketch that shows all possible resources and the navigations between them. The second sketch is a JSON sketch that shows the details of what a list and an item response look like. Of course, you should be using the Apiary editor to create these sketches.[98]
Your Apiary Starting Sketch
To begin, open your browser and enter the address for the Apiary editor. Next, create a new API project by opening the drop-down menu at the top of the page and typing in a new project name (for example, credit-check-sketch) and pressing the Create API button. This opens a new project preloaded with a sample API sketch. You can delete everything in the left panel after your sketch name (# credit-check-sketch). Now you’re ready to start creating your own sketches for the CreditCheck service.
The Credit-Check Resource Sketch
The first sketch is an HTML version that shows each of the resources your API will expose along with links between those resources to show the workflow from one step to the next. Recall that our ALPS description document has the following steps:
- Home
- CreditCheckHistory
- CreditCheckForm
- CreditCheckItem
The first step is to create these four elements in our Apiary blueprint document. If you look in the before folder for this solution in the code download for the book, you’ll find a file (credit-check-resources.apib) you can use to start with. Just open that file in your editor and copy-paste the text directly into your Apiary editor in your browser. You should see three resources already sketched out for you: Home, CreditCheckForm, and CreditCheckItem. It should look something like this:
| | FORMAT: 1A |
| | HOST: http://polls.apiblueprint.org/ |
| | |
| | # credit-check-sketch |
| | |
| | The public API profile for BigCo's CreditCheck service. |
| | |
| | ## Home [/] |
| | |
| | Root resource; points to other resources/actions in the service |
| | |
| | ### Root [GET] |
| | |
| | + Response 200 (text/html) |
| | |
| | <html> |
| | <head> |
| | <title>Home</title> |
| | </head> |
| | <body> |
| | <h1>Home</h1> |
| | <ul> |
| | <li> |
| | <a href="/list">CreditCheck History</a> |
| | </li> |
| | </ul> |
| | </body> |
| | </html> |
| | |
| | ## CreditCheck History [/list] |
| | |
| | Returns a list of past credit rating records. |
| | |
| | |
| | ### List [GET] |
| | |
| | + Response 200 (text/html) |
| | |
| | <html> |
| | </html> |
| | |
| | ## CreditCheck Form [/form] |
| | |
| | Returns the input form for making a credit-check request. |
| | |
| | ### Form [GET] |
| | |
| | + Response 200 (text/html) |
| | <html> |
| | <head> |
| | <title>Credit Check Form</title> |
| | </head> |
| | <body> |
| | <h1>Credit Check Form</h1> |
| | <ul> |
| | <li> |
| | <a href="/">Home</a> |
| | </li> |
| | <li> |
| | <a href="/list">Credit Check History</a> |
| | </li> |
| | </ul> |
| | <form action="/list/123"> |
| | <label>Company Name</label> |
| | <input name="companyName" /> |
| | <input type="submit" /> |
| | </form> |
| | </body> |
| | </html> |
| | |
| | ## CreditCheck Item [/list/123] |
| | |
| | Returns a single credit check record |
| | |
| | ### Item [GET] |
| | |
| | + Response 200 (text/html) |
| | |
| | <html> |
| | <head> |
| | <title>Credit Check Item</title> |
| | </head> |
| | <body> |
| | <h1>Credit Check Item</h1> |
| | <ul> |
| | <li> |
| | <a href="/">Home</a> |
| | </li> |
| | <li> |
| | <a href="/list">Credit Check History</a> |
| | </li> |
| | <li> |
| | <a href="/form">Credit Check Form</a> |
| | </li> |
| | </ul> |
| | <p>RatingItem goes here...</p> |
| | </body> |
| | </html> |
You can use this starter as a guide for completing the rest of the HTML sketch. You just need to add an HTML document for the CreditCheckHistory resource. Nothing fancy. Just make something that can act as a placeholder to show the eventual workflow of the API. You can find a finished version of this apib document in the completed folder for this solution.
Because this sketch is in HTML format, you can use your browser to “test” the workflow by loading the starter URL in your browser and following the links back and forth in the API.
The CreditCheck Response Sketch
You’ll notice that our HTML version of the sketch didn’t actually show what the response data looks like. It just showed the resources and the links between them. So in this second sketch, we’ll actually show the details of the response data, and this time we’ll do it using the JSON format—the most common API response format to date.
First, start a new sketch (credit-check-responses), and when the default sample content appears, remove it to make room for your two sketches (creditCheckHistory and creditCheckItem). Remember, you only need to show the detailed response bodies in this sketch. No workflow or links. You can paste the starter document in the before folder called credit-check-responses.apib into your Apiary editor page. It should look like this:
| | FORMAT: 1A |
| | HOST: http://polls.apiblueprint.org/ |
| | |
| | # Credit Check Responses |
| | |
| | Public API profile for BigCo's CreditCheck service. |
| | |
| | ## Credit Check History [/list] |
| | |
| | Returns a list of past credit rating records. |
| | |
| | ### List Past Credit Checks [GET] |
| | |
| | + Response 200 (application/json) |
| | |
| | { |
| | "creditCheck" : [ |
| | { |
| | "id" : "123", |
| | " |
| | }, |
| | { |
| | "id" : "456", |
| | }, |
| | { |
| | "id" : "789", |
| | } |
| | ] |
| | } |
| | |
| | ## Credit Check Item [/list/123] |
| | |
| | Returns a list of past credit rating records. |
| | |
| | ### Single Credit Checks [GET] |
| | |
| | + Response 200 (application/json) |
| | |
| | { |
| | "creditCheck" : [ |
| | { |
| | "id" : "123", |
| | } |
| | ] |
| | } |
These two responses just need to be filled in with all of the property elements found in the ALPS description you created in the last exercise (see Solution for Chapter 5: Describing APIs). You can check your work against the credit-check-responses.apib document in the completed folder for this exercise.