Are APIs Semantics?

There is a blog post Thinking Outside-In: How APIs Fulfill the Original Promise of Service Oriented Architecture┬áby Anders Jensen-Waud. A comment on LinkedIn referencing this article asked if “APIs by themselves begin to address semantic interoperability?” I don’t think so and my reason for thinking semantics is not defined in the API itself is as follows.

I have been creating APIs for hospitals for years and have found an API by itself doesn’t make something more likely to be semantically interoperable. I have found it’s more important to get the community that builds and uses the APIs to use the same vocabulary with the same context and out of that understanding APIs can be developed that are semantically congruent. Without those people sharing understanding then they each go off and develop their parts and after they have developed each part they come back to integrate it with the whole and found that even though they used the same property names or class structure, they used them with different intentions. For example, this really happened once. One team of API creators inside a company started with the same product goal as a second team in the same company, to track locations of things on a map. They each knew that they were going to use polygon data structures and each point in the polygon was going to have a X and Y property. Three months after each building their components, they came together to integrate their parts and they didn’t work, because they operated with different assumptions. One team’s processing logic used Cartesian points where the X,Y origin is in the bottom-left and the other team used Raster points, where the origin is in the top-left. No one identified semantics as a deliverable, because the teams ionly thought the code/API was the deliverable. The semantics should have also been a deliverable and occurred before the production of an API.

The insight I want to share is that semantics is a shared context and understanding. APIs and code itself are just symbolic processing. The symbols themselves do not inherently carry the meaning, but the common understanding among people can use the symbols in the same way.

OAuth Server and Bearer Token Size Limit

I was building an OAuth Server using the Microsoft stack of OWIN components and learned that it is not good to keep adding an indefinite number of claims to the bearer token returned by the OAuth Server. There is no hard limit, but if you create a bearer token over 2KB then you might start to see problems when using different tools. This started to happen in a software project I was working on when the number of claims created a bearer token over 4KB. A tool the QA team was using for testing started to have issues.

As a rule of thumb, I try to limit bearer tokens to under 2KB now.