What is a Web API?

It's a bit ambiguous to say Web API as there are two kinds:

1. The kinds of APIs accessible by scripting (i.e., JavaScript) within the Open Web Platform (OWP).
2. The combination of service infrastructure, access URIs, and responses provided by a service on the Web (e.g. Twitter's API).

Right now, we're concerned about the former. Next week we'll do the latter.

Functional Areas

• Core resources: document (DOM), style, window, etc.
• Events: information about occurrences such as touch events, progress, timers, etc.
• Device APIs: location, time, cameras, audio, file access, etc.
• Media: resource metadata, playback controls, etc.
• Environment/Packaging: Offline mode, widgets, storage, etc.
• Communication: Web requests, messaging, workers, streams, etc.

...and many, many more.

You can read a full list on the W3C website status page.

Anatomy of a Web API

Take a look at the Geolocation API Specification

1. Introduction / Scope — where might you encounter this API? Not all are required within the OWP...
2. Security & Privacy — good specifications indicate what a user and implementer should expect (e.g. prompts for geolocation access).
3. API description — the final details of the behavior, methods, and parameters.
4. Use cases — hopefully they included or referenced some use cases. It isn't always obvious whether the intent was to cover your specific use case.

WebIDL Example

[NoInterfaceObject]
 interface NavigatorGeolocation {
   readonly attribute Geolocation geolocation;
 };

 Navigator implements NavigatorGeolocation;            
         

So, window.navigator.geolocation is your starting point:

[NoInterfaceObject]
 interface Geolocation { 
   void getCurrentPosition(PositionCallback successCallback,
                           optional PositionErrorCallback errorCallback,
                           optional PositionOptions options);

   long watchPosition(PositionCallback successCallback,
                      optional PositionErrorCallback errorCallback,
                      optional PositionOptions options);

   void clearWatch(long watchId);
 };            
         

Note: We will talk about callbacks next time.

Example: Speech Synthesis

• Developed by the Speech API Community Group.
• There is an API specification, but not a recommendation.
• And it works!

function sayIt() {
   var u = new SpeechSynthesisUtterance(
               'Hello, Veronika! ' + 
               'Would you like to see a picture of a kitty cat?');
   speechSynthesis.speak(u);
}
         

(and a good way to entertain a 2-year-old whilst making slides)

A more interesting demo.