This is the second post in our series on the design of web services at OCLC. In our first post on the series, we discussed the overall strategy at a very broad level. This time we will move way over to the other end of the spectrum of granularity and talk about how we mint our HTTP URLs. Again, our thinking has evolved over the past few years, but is coming to a stable place. As we craft new APIs and refactor existing ones on the WorldShare Platform, we will use the patterns below. We hope that by sharing this information, developers will see patterns emerge that can contribute to a deeper understanding of how to integrate with the WorldShare Platform.
The fundamental question we must first answer with our URL pattern is the purpose it serves. A URL, or uniform resource locator, is a reference to a specific resource on the World Wide Web. For our suite of web services, those resources define endpoints at which data and/or functionality is available on OCLC servers. Insofar as it is a reference, we are providing an addressable name for things in our suite of services. Understanding this use of URLs as names is critical to understanding the logic behind the pattern.
OCLC is a global company serving libraries all over the world. To provide the best possible service, we have server environments (“data centers”) on 3 continents and in 4 countries:
We deploy our software in multiple geographic regions primarily for two reasons:
The first thing a WorldShare Platform URL needs to do is just get a web service client request close to a server that can fulfill its request. In other words, it needs to send the client’s request to the correct continent or regional data center. The domain names we use in our URL patterns route web service client requests to the appropriate regional data center. Not all of our applications and data are deployed globally, so we have two primary patterns for our domains.
When routing a request to a service that only exists in a single location, we use the following pattern for the domain name portion of a URL:
Today, URLs with domain names following this pattern typically route to the original OCLC headquarters data center in Dublin, OH. Additionally, we may also optionally identify a particular library to localize the web resource that is being accessed.
When clients make a request using a URL containing a domain name like the following:
it is routed to the regional data center nearest to the library whose data is being accessed. The “library” token in the domain name will usually be a string chosen by the library to distinguish its resources from others’.
Once the global Domain Name System has routed your requests to the right regional data center, the next piece of routing happens through the path portion of the URL. The design of the URL path is where application and domain-specific semantics come into play. Each portion of the URL, the individual strings of characters separated by the forward slash, becomes a token with a particular meaning. Our pattern divides the URL path into the following tokens:
And finally, after the path, we use an extension for URL-based content negotiation. Where possible we base the content types on IANA defined mime types, such as application/atom+xml.
Therefore, if we see the following URL:
it can be read as the following:
The XML representation of the work identified by #1234 from our sample service localized for the OCLC Sandbox Institution, the institution whose OCLC symbol is “OCPSB”.
The OCLC Developer Network supports the use of OCLC Web Services—a set of tools and APIs that expose data and services for WorldCat and our member libraries and partner institutions or companies. learn more »
© 2010 OCLC Domestic and international trademarks and/or service marks of OCLC Online Computer Library Center, Inc. and its affiliates