This post looks at the creation of a basic proxy API. It is the simplest kind of API where we simply proxy an existing service. The key reason that we want to do this is that we can use API management to register, track and control apps and app developers and the use of our API resources. A simple proxy API will be the most common use of APIs typically.
The Source REST Service
For the purposes of this test we will select a publicly available service that requires no additional registration or use of application keys. In this case we are going to use one of the public APIs provided by the BBC to get information about various programmes and schedules. The API is documented here:
BBC Programme Developers Page
It provides a set of information about schedules, genres and individual programmes. We will use this to get upcoming episodes of a particular programme.
The API follows exactly the same URL model as the BBC website. So, if we want to look at upcoming episodes of Saturday Kitchen we simply need to use a browser to get to the programme's website. The programme's id is contained within the link.
To help our eventual app developers we need to get some sample JSON output from the REST service. To do this we simply use the "upcoming" method. We can paste the following link into a browser.
http://www.bbc.co.uk/programmes/b006v5y2/episodes/upcoming.json
Copy and paste the output message into a text editor as we will need it soon when we create the API.
Create and Test the API
We can now create our API. Log into the Cast Iron Web API Builder at:
https://webapi.castiron.com/webapibuilder
Create a new API called "BBC Programmes API", give it a context of "bbcProgrammes", add a description and click "Create".
The basic API is now complete but we need to do one more thing before we can test. We need to add at least one entitlement to the API. Return to the main API page and click on the "Entitlements" tab.
Add an entitlement called "Basic Entitlement" and give it a description and a number of calls per minute and click "Add".
Click on the "Test" tab, select the GET resource and the "Test Application". Paste the programme id into the "programmeId" parameter and then click "Test".
That completes the creation of a basic proxy API.
The Source REST Service
For the purposes of this test we will select a publicly available service that requires no additional registration or use of application keys. In this case we are going to use one of the public APIs provided by the BBC to get information about various programmes and schedules. The API is documented here:
BBC Programme Developers Page
It provides a set of information about schedules, genres and individual programmes. We will use this to get upcoming episodes of a particular programme.
Schedules
/:service/programmes/schedules{/:outlet}
/:service/programmes/schedules{/:outlet}/:year/:month/:day
/:service/programmes/schedules{/:outlet}/:year/:month/:day/ataglance
/:service/programmes/schedules{/:outlet}/yesterday
/:service/programmes/schedules{/:outlet}/today
/:service/programmes/schedules{/:outlet}/tomorrow
Genres
{/:service}/programmes/genres/:genre1{/:genre2{/:genre3}}/schedules
{/:service}/programmes/genres/:genre1{/:genre2{/:genre3}}/schedules/:year/:month/:day
{/:service}/programmes/genres/:genre1{/:genre2{/:genre3}}/schedules/:year/:month/:day/ataglance
{/:service}/programmes/genres/:genre1{/:genre2{/:genre3}}/schedules/upcoming
Programmes
/programmes/:groupPID/episodes/upcoming
/programmes/:groupPID/episodes/upcoming/debut
/programmes/:groupPID/episodes/player
The API follows exactly the same URL model as the BBC website. So, if we want to look at upcoming episodes of Saturday Kitchen we simply need to use a browser to get to the programme's website. The programme's id is contained within the link.
To help our eventual app developers we need to get some sample JSON output from the REST service. To do this we simply use the "upcoming" method. We can paste the following link into a browser.
http://www.bbc.co.uk/programmes/b006v5y2/episodes/upcoming.json
Copy and paste the output message into a text editor as we will need it soon when we create the API.
Create and Test the API
We can now create our API. Log into the Cast Iron Web API Builder at:
https://webapi.castiron.com/webapibuilder
Create a new API called "BBC Programmes API", give it a context of "bbcProgrammes", add a description and click "Create".
Click on the "BBC Programmes API" link to edit the API.
Add a "GET" resource with a URI of: programmes/{programmeId}/episodes/upcoming.json
Click on the link to edit the API resource.
Select the "Proxy" checkbox and enter the following address for the proxy:
http://www.bbc.co.uk/programmes/
Note that API Management will match the URI up to "/programmes/" and append the remainder of the URI from the API resource.
Paste in the sample JSON response that you saved earlier. Note that when you paste in the message the JSON will be formatted assuming the JSON is valid. If it is invalid the JSON will not format nicely and the response body section will be shaded red to indicate the error.
The basic API is now complete but we need to do one more thing before we can test. We need to add at least one entitlement to the API. Return to the main API page and click on the "Entitlements" tab.
Add an entitlement called "Basic Entitlement" and give it a description and a number of calls per minute and click "Add".
The API is mow complete and we can test it. Return to the "Resource Definition" tab and activate the resource by clicking on the Activate icon. Click "OK" once the resource activates successfully.
Click on the "Test" tab, select the GET resource and the "Test Application". Paste the programme id into the "programmeId" parameter and then click "Test".
After a moment you should see a successful response from the service.
That completes the creation of a basic proxy API.
No comments:
Post a Comment