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.

Employing AI

I plan on writing two blog posts in the coming days.

  1. Hiring My First AI Resource/Employee
  2. Managing a team of AI Resources/Employees

These are not about employing people, but employing AI agents for different business responsibilities. This is an area that I think will grow more relevant as our digital assistants get smarter and more manageable.

First, we employee individual assistants, like Cortana on Windows. I use this assistant to add appointments to my calendar or check the whether. I also use Buffer to schedule tweets for my business. Buffer will let me manually schedule a time or “pick the best time” to send my tweet, based on its own intelligence.

I use MailChimp to send email newsletters for my business. It has similar smarts to Buffer and can tell me the quality of the individuals I am emailing, compared to their interactions with other newsletters also sent through the service.

Now that I’m relying on these AI agents, it’s time for me to raise this abstraction layer up a level and apply intention to managing them individually and as a team. Ultimately, I don’t want my AI agents to be silos of activity, but I want Cortana to interact with Buffer and MailChimp and coordinate Twitter and MailChimp activity. I want these services to monitor my Google Analytics to know when one of the tweets or email newsletters is increasing traffic to my site beyond the original newsletter links being clicked. How can I generate a positive feedback loop?

New 3D Print Clothes Website

3D Print Clothes

3D Print Shoes

I have recently launched a new website for 3D printing clothes. has two purposes for consumers and designers.

3D Print Clothes for Consumers – This is a place where anyone with a 3D printer, or someone with access to the many local services (makexyz) that can 3D print items for you, to make their own unique clothes. We use the term clothes loosely, so it might be necklaces, shoes, belt buckles or anything else.

3D Print Clothes for Designers – Talented individuals or organizations that make 3D models for download can distribute their own clothing line through this website. If you give your designs away for free (Creative Commons) or just ask for donations then you can start a shop risk free right now for free. If you want to have a more advanced shop that charges per 3D print or a fixed fee per download then the website also lets you do that for a low monthly charge.

Software and the Advantage of $0 Incremental Cost

Software has the advantage of being able to be written once and distributed millions of times with near $0 incremental costs. For example, if it costs $20,000 to write the software for one customer, then it will cost $20,000 for that software to be produced and distributed to 1 customer or 1000 customers.

A lot of software business owners are aware of this advantage, but I also think a lot of owners think they get this benefit for default just because they are software creators. Just because you produce software does not mean you get $0 incremental cost by default. It takes design, not introducing technical debt and taking analysis of customer wants and needs to the next step, synthesizing solutions to patterns of user goals instead of responding to individual requests.

If it takes 100 man hours to write a piece of software and will require 20 hours for you to re-write it for another customer then you do not have a $0 incremental cost software product. You will have branches of custom software, each with their own customer.

So, it’s important to also do the team activities that find and communicate patterns of user goals to the whole team and design the customization and extensibility points. Customization points are best content, like replacing a string with another string. For example, if customers want their own logo in the app, then this would be a customization point.

Integration points are best when you want hooks that will be invoked with custom processing. For example, if the user goal pattern is people want a notification to be sent when a field in your software has a value entered, then how the notification is sent might be designed as an integration point. This is because one customer might want an email notification and another customer might want a text message.