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:
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
If you need help or advice with this step, see our API Design Assistance page.
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:
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.
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:
This is the URL that your API subscribers will use. It is fully protected by WebServius, and requires a valid API key to access.
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.
If you go to the Services tab, you will see a URL next to your service that looks like this:
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.
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:
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:
Copyright © WebServius 2008-2013