Adding resources to API Modeler

Modeling and testing APIs

1. Getting started
2. Prerequisites
3. My first API
4. Adding resources
5. Import & Export
6. Managing API specs
7. Testing with Mock apps
8. Advanced topics

Resources

Every API needs resources that describe what objects it will work with. For our BookStore API we?ll create a books resource. To do that click on Add Resource (the large orange button). The resource path (the end of the URL) should be /books/{id} as it will be the generic path for all of our books requests. For this tutorial we?ll only look at the GET and POST operation, so click those and hit Save.

Our BookStore will be used on both mobile devices as well as desktops. For mobile devices we want to send back less data. To make sure our API understands that, we?ll add a query parameter to the GET operation. To do that, simply click + Query parameter. Let?s call the parameter device, with a default value of pc and the type can be string.

The request

When you?re building RESTful APIs the GET operations usually don?t have a request body (it is considered bad practice to do that). The POST method on the other hand should have a request body that tells the API what to do. Click on POST on the left hand side of the screen to switch over to that method and click on + Body parameter right below Request Body Parameter to open up the next screen.

This screen has a bunch of options. In the big editor window you can add a sample message that you expect to send to the API and we?ll turn that into a JSON schema. That is a lot easier than crafting a JSON schema by hand. When we POST a book, we essentially create a new book in our inventory so let?s create the sample message like below

 {     "title":"My new book",     "author":"Leon Stigter",     "description": "A new cool book on APIs",     "price":29.95 }

Now click the giant orange button to Generate Schema. As a best practice you should give your schema a name in case you want to use it as a reference later. So in this case put BookSchema where it now says GiveNewSchemaNameHere and hit Save (yes, a blue button this time).

The responses

Obviously APIs need to be able to respond to what happens on the server side as well, so now let?s focus on the responses that the API can return. In this case both the GET and POST methods can send back a response.

Still on the POST operation, switch to the Response side by clicking the button on the right hand side of the screen. That will give you an overview of all the responses that your method can send back. We?ve set you up with a 200/OK response to which we can add some sample data. To do that, click on the card and click on Generate Schema from Sample Data. If you get a pop-up saying New generated schema will overwrite existing one, you can safely click Continue. Now you can enter a sample response message in the same way as you did for the request. Let?s use the below message and call it POSTResponseSchema

 {     "internalID":"1234AAX",     "title":"My new book" }  

You can add more responses by clicking on the large + sign and select the status code (for example 404 when a resource isn?t found or 500 for internal errors). The process of adding responses from that point on is the exact same as we did above.

Now let?s go over to the GET method to add a response there as well. For the GET method we want to reuse the BookSchema as our GET method should return a single book. To do that click on the 200/OK response card and select Reference for the schema. Now you can start typing BookSchema and it should show up in the list. As you select it, the schema will show up in the text editor and you can click the blue Save button.

Preview

Great! So we now have an API documented and ready to be implemented (or tested). To preview what the API will look like, click on the Preview button at the right hand side of the screen (the big eye icon).

Check!