One of the topics that came into relief for me quite clearly recently is the idea of core domains and their application in API design. This happened as part of our design meetings for BYU's University API. When I say "core domain" I'm thinking of the concepts taught in Domain-Driven Design (DDD) and made clear in Implementing Domain-Driven Design (iDDD). (Aside: if you're in OIT and would like a copy of iDDD, stop by my office.)

DDD uses the terminology "core domain," "supporting domain," and "generic domain" to describe three types of sortware systems you might be building or using and how your organization should relate to each. My goal here isn't to expound on DDD; that's a different article. But I think you get the idea of what a core domain is: the "core domain is so critical and fundamental to the business that it gives you a competitive advantage and is a foundational concept behind the business."

Suppose you're an online merchant, for example. The core domain is probably the order processing system and orders are the fundamental artifact you worry about. Inventory is important, but it's a supporting domain. Customers are important too, but they're also supporting. The thing you worry about day in and day out is the order. The object that links items in the inventory, a customer, and a payment transaction.

Consequently, if you were designing an API for an online merchant, you'd probably make orders a top-level object in the API:

/orders

This would for the heart of everything you designed.

Applying this logic to a University API is harder. Universities tend to be pretty complicated places with lots of constituents. For example, it we were to just ask "what business is a university in?" The answer, at the core, is that universities are in the credentialing business. We certify that students have performed at required levels in prescribed sets of classes. Looked at this way, an enrollment object (marked as "complete") might be at the heart of a university API. But it turns out that almost no university systems care about enrollments as such, at least not the same way an ecommerce company cares about orders.

Universities care about students, courses, programs, classes, instructors, and classrooms. These are the key objects that fuel much of the university IT systems. Enrollments are in there, of course. You can ask what students are in a class and what courses a student is in or has completed. But you're always starting from the class or the student, not the enrollment itself.

Which of these is a core domain and which are supporting depends on your context. There's another key concept from DDD: "bounded contexts." The API needs to support each of these core objects, but how the API behaves with respect to a given object type depends on the context you're in. If I'm looking at a student from the context of tuition payments, I care about very different things, than if they've just stopped by the counseling center.

The University API will support different contexts. Trying to support these very different contexts from a single model in unwieldy at best and likely impossible. But that doesn't mean that the University API can't supply a consistent experience regardless of the context. The University API should feel like a well-designed system. This is accomplished through well-known principles of API design including consistency in naming, identifiers, use of plurals, error messages, headers, return values, and HTTP method semantics. Our goal is that developers who've used the API in one context and learned its idioms will be able to easily transfer that experience to another and that using the API in that new context will feel natural and intuitive.