Msc Project Proposal


API design is increasingly made more difficult when having to debate vocabulary. Within this paper, we will discuss how we can use an open-source vocabulary coupled with a query language to help drive a common API approach. We will also show how to extend that common vocabulary.

We will drive the API design using a user-centric approach, to first take the initial requirement and model against a common vocabulary.

From there we will then take another requirement and extend upon the common vocabulary and introduce the concept of extensions.

All the models that are to be delivered will be fully decoupled using SOA techniques of API design, and we will model those code produced using UML

Area of study

When starting a software project, you start by evaluating the problem domain, then design a system around that domain. One area of system design that is problematic is that of the terminology used, the way you describe a system, and the way you design that systems interface. The names chosen for properties on data types are normally dictated by the engineers building the system.

Let’s take the Address data type, built by two separate engineers, one might describe the County as County and another County as State. If these two systems are meant to talk to each other, then a mapping layer would need to be built to understand the differences between the two properties. In this example, the mapping would be one to one.

Once the system is developed, and in use, the vocabulary used often does not change. It’s deemed too risky to make changes, and there is no easy way to deprecate terms and introduce new ones. More often what is done, is that the system goes through a process of versioning rather than evolving the contract.

To be clear, when we talk about the vocabulary of a system, we talk about the contract between the client and the server. The contract is the model of data the client queries for and the model that the server returns to the client.

If a common vocabulary was introduced upfront, then a mapping layer would not necessarily be required, and both systems would talk the same language.

An example of where a common language has been introduced is within the world of Search Engine Optimization (SEO). When a web crawler decides to crawl a web page, it makes choices about what that page is about. You can add additional metadata to that page using a structured data vocabulary called SchemaOrg.

There have been two other approaches to system design using this vocabulary. One to surface this vocabulary through OpenAPI, and the other through GraphQL, where the latter was unfinished. Both approaches cover somewhat the surfacing of a model but does not deal with evolving, extending and querying that model, this is the gap I am going to address.

Programme of work

Given the problems described in the previous section, my approach for addressing this gap are;

To start, I will examine how the previous two previous attempts have been built; look at how they structured their domains and where they were lacking in terms of extensibility and querying.

The project will be focused on API design; and for this, a case study will then be introduced; this case study will form the basis on the problem domain.

I will then start to look at how a domain-driven design (DDD) approach can help to shape an API's vocabulary, as a domain-driven approach models both the data and behaviour of a system [3].

However, a domain-driven approach does not necessarily tackle the gap of multiple vocabularies within one company, for this, we will need to then look at approaches to DDD that can be used to close this gap, most notably Schema.Org.

I will then look at extensibility, and how certain approaches to modelling DDD within API development can be done, examining the multiple approaches to take.

Once modelling and extending the design have been covered, I will then look at querying, and how you can take a common API vocabulary and then extend this to include additional company-specific terms, again, referring back to the case study.

Lastly, I will look at how to deprecate terms within the vocabulary, examining how we will version the API when the vocabulary changes.

The outline of the dissertation will follow the following structure;

Table of Contents
1. Introduction
2. Background
3. Case study - Orion Medical 
4. Model design and implementation
5. Evaluation & Reflection
6. Conclusions and Future Work    

Appendix I  - Code

The expected outcome from the project will be a view on how you can represent multiple vocabularies within the confines of an API, whilst being able to also address the ability to extend and remould that API over time.

To develop the API, the following tools will be used;

Visual Studio - To build the API, this will be done in C#. DrawIO - To model data flow from client to server Postman - To test visually the API I intend to develop the API using a test-driven approach to model the domain in a Gherkin language. Gherkin should fit this model well for modelling a domain-driven approach as it is unique to adapt to modelling behaviour and data of a system. A key outcome of this project will be how well the API at the end understood.

How well we communicate is determined not by how well we say things, but how well we are understood. [4]

Project plan

September 2019

Project Proposal signed off [Milestone] Github repo created

Research of existing solutions

Introduce case study Write user stories in Gerken, to drive the initial prototype (Dependency on Case Study) Create UML diagrams to highlight data flow in, and out of the system.

Initial skeleton of a prototype started GraphQL Endpoint Article datatype exposed One query using an id

October 2019

Initial skeleton of a prototype Completed [Milestone] Full end to end test based on the Gerkin stories

Add extensions story Create user stories Create the basic extensibility points

End of June prototype completed. [Milestone] Dissertation will be at a high level with what has been built to this stage

November 2019

Discuss the storage model vs the presentation model, and how SchemaOrg is represented at both levels.

Discuss how to walk a SchemaOrg model both down the model and back up again.

Mid-July, first draft completed. [Milestone]

December 2019

First two weeks of August, get a second draft completed.

Refinement of document and codebase.

January 2019

Hand dissertation in.

Ethical, Legal, Social, and Professional Issues I don’t see this project affecting any of these issues as it is just API design.


SchemaOrg Article webpage,, Last checked May 2019 SchemaOrg Extensions webpage,, Last checked May 2019 Patterns of Enterprise application architecture, Martin Fowler, 116, 2007 Writing Great Specifications, Kamil Nicieja, Chapter 2 - Page 1, 2017