Starbucks API Explorer view
This post will deviate from the earlier posts on networking. Here I want to describe the UI and implementation for trying out REST based APIs. Here I will address questions such as what should the UI look like ? Should it be server side implementation or client side implementation. Should it be implemented in a browser or should it be a mobile device application ?
For now we will refer to our implementation as an app.
Next, Let's look at a few use cases.
The most common use case for the UI is to target the REST APIs from a single provider. This means its targetting a known endpoint and port. In fact, the URI is structured in a way that users are scoped down to the most variable part towards the end of the URI. Thus the app should only ask for the resource qualifier and retain the value from the previous usage.
Another thing is that the the method such as GET or POST should be easily selected. On Mobile devices, auto complete works better than drop down but there is no preference between the two.
Also additional methods to auto populate query parameters should be made available such as to get tokens
The query string itself can be constructed with a name value parameters where the names are populated before hand. Each API supports a pre-canned set of query parameters and request body.Therefore name value parameters should be added on user wish to specify more. Initially this list could be a collapsible pane hiding the complexity of additional parameters unless the user wants more and more fields to populate. Typing on mobile devices is hard so reliance on user session and auto-complete feature could come useful.
The choice of method should additionally define the Request Header and Request Body.
The request header can also be thought of comprising name value pairs so the treatment given to query parameters can be the same for request header fields.
The choice of return type such as JSON or XML need not be specified in the Request header. These are very frequently used fields and hence they are candidates for independent controls by themselves.
This post will deviate from the earlier posts on networking. Here I want to describe the UI and implementation for trying out REST based APIs. Here I will address questions such as what should the UI look like ? Should it be server side implementation or client side implementation. Should it be implemented in a browser or should it be a mobile device application ?
For now we will refer to our implementation as an app.
Next, Let's look at a few use cases.
The most common use case for the UI is to target the REST APIs from a single provider. This means its targetting a known endpoint and port. In fact, the URI is structured in a way that users are scoped down to the most variable part towards the end of the URI. Thus the app should only ask for the resource qualifier and retain the value from the previous usage.
Another thing is that the the method such as GET or POST should be easily selected. On Mobile devices, auto complete works better than drop down but there is no preference between the two.
Also additional methods to auto populate query parameters should be made available such as to get tokens
The query string itself can be constructed with a name value parameters where the names are populated before hand. Each API supports a pre-canned set of query parameters and request body.Therefore name value parameters should be added on user wish to specify more. Initially this list could be a collapsible pane hiding the complexity of additional parameters unless the user wants more and more fields to populate. Typing on mobile devices is hard so reliance on user session and auto-complete feature could come useful.
The choice of method should additionally define the Request Header and Request Body.
The request header can also be thought of comprising name value pairs so the treatment given to query parameters can be the same for request header fields.
The choice of return type such as JSON or XML need not be specified in the Request header. These are very frequently used fields and hence they are candidates for independent controls by themselves.
Next, the Response can be rendered either as plain text, or with markups. If the JSON is being rendered, separating out the name value pairs on separate lines may be helpful. Similarly XML may have each element on a new line. Indentations can help in both cases.
Long strings are common in several fields of the above mentioned form, therefore splitting it and displaying it in a vertical format will help visually. Even for URLs, we could consider keeping endpoints and resource locator apart. The strings are difficult to scroll in the limited breadth of a portfolio styled screen.
Having described the page for the composer of the HTTP request, it is important to note that endpoints are usable only when they are documented. Hence the Explorer view must provide a link to the corresponding documentation of each API. There could be a separate view to list the endpoints. This is helpful to browse all that is available.
Also, when we talk about the overview of the pages seen when the user opens the application, we list these pages such as an API browser to show all endpoints, a Composer to make requests, a capture to show the requests and responses capture and to browse the responses in detail. 
No comments:
Post a Comment