Hi Dave,

Thanks for checking out the API. You’re right that it’s a little awkward. The primary reason for this design decision arises out of Medium’s history of titles. Every post on Medium was originally required to have a title, but that requirement was dropped sometime last year as responses and conversation were made more integral to the product. When you add a title to a post on Medium, it isn’t necessarily part of the content. Of course, titles are still important for post listings, so for posts that don’t have a title, we synthesize one from the first paragraph.

When we came to build the API, we had a problem. Most pre-existing sources of posts, like RSS, or WordPress, have titles. Clearly, that’s the title that should show up in post listings. But not all writing has a title, and it shouldn’t have to. This post, for example, does not have a title.

We don’t want to mess with the content that the user has sent us. Do we put the title in as an H1 at the top, or an H2? As a regular paragraph? What if a user explicitly doesn’t want one? Later on, if and when the API gains the ability to respond to existing posts, it’s far from clear that those posts would want a title in the body. We’d much rather have the user get exactly what they said.

Now, in specific cases, we can make a good judgement on what the user’s intent is. With our WordPress plugin, for example, every cross-posted post has a title, so we put the title into the content field as an H1. With IFTTT, it’s easy enough to just put:

<h1>{{EntryTitle}}</h1>

in the content field, before {{EntryContent}}.

Our IFTTT recipe for RSS to Medium should also do that — an earlier draft of it did — and we’ll fix that to give people a better template.

Although the title situation is awkward, it is documented, and it supports multiple different use cases. It certainly won’t change for v1 of the API — we have people building on the platform already. But, we’re developing the API in consultation with the people who are building on it, so we may well revisit this for v2, whenever that comes to pass.