Integration Example: Acme Weather API

Let's walk through an example showing the steps required to connect your API to WebServius.

In this hypothetical example, suppose you work for a company called Acme Weather, and want to provide an API that serves weather information for the United States. Here is what you would do:

1. Create the actual code for your API

For example, you could create a program called getTemperatureForecast.php that takes a request of the form getTemperatureForecast.php?city=Miami and returns an XML reply of the form <temperature>72</temperature>.

If you need help or advice with this step, see our API Design Assistance page.

2. Host the API endpoint at a secret URL

The users of your API should never call it directly, but should call it through WebServius instead. This ensures that all access to your API will be protected, controlled and accounted for. To prevent users from calling your API directly, host it at a secret URL, for example:

http://api.AcmeWeatherExample.com/479201185943218/getTemperatureForecast.php

Security Note: To prevent the secret URL from being discovered in access logs (including those of proxy servers), you can host your API endpoint at an HTTPS address instead of HTTP, with an SSL certificate from a trusted certification authority. This is usually only required when dealing with especially valuable data, or when your API is hosted in a shared hosting environment where you do not trust the hoster. Other, more secure methods of hosting an API endpoint will likely be supported by WebServius in the future, but may require more work on your part.

3. Connect the API endpoint to WebServius

Sign up for an API provider account on the WebServius site and choose "acme" as the provider short name. Go to the "Services" tab, click on "Enroll a New Service", and create a new service. Choose "weather" as the service short name, and enter your secret URL in the Service URL box ("http://api.AcmeWeatherExample.com/479201185943218"). This URL will only be known to you and WebServius, and will never be revealed to your API subscribers.

If you now go to the Services tab again and look at the service you just created, you will notice that it now has a second URL:

http://svc.webservius.com/v1/acme/weather

This is the URL that your API subscribers will use. It is fully protected by WebServius, and requires a valid API key to access.

4. Set up a Usage Plan and a Package

Go to the Services tab, and click "Usage Plan" next to your service. Create a new plan — for example, you can name it "Regular Pricing" and set the price at $0.003 per call.

Go to the Services tab again, and this time click "Packages" next to your service. Put together a package called "New User Package" using the "Regular Pricing" plan, a "Full Access" policy, and no license agreement (this is the simplest type of package you can create). From this point on, your API is fully configured and is ready to be offered to subscribers.

5. Give the subscription link to your API users

If you go to the Services tab, you will see a URL next to your service that looks like this:

http://www.webservius.com/cons/subscribe.aspx?p=acme&s=weather

Give this link to your potential API subscribers. For example, you can create a button on the www.AcmeWeatherExample.com site that says "Subscribe to Our Weather API", leading to the link above.

6. Developers will subscribe to your API and use it

When developers subscribe using the "Subscribe" button you created above, they will be given a Secret Key that uniquely identifies them. The Secret Key is an alphanumeric string, such as gKoR4bnm98TYh01. Your API subscribers can then make requests like so:

http://svc.webservius.com/v1/acme/weather/getTemperatureForecast.php?city=Miami&wsvKey=gKoR4bnm98TYh01

WebServius will log the request, charge the customer the price you defined earlier ($0.003 per call in this example), and forward the call to your secret API endpoint like so:

http://services.acmeweather.com/479201185943218/getTemperatureForecast.php?city=Miami