Yesterday, Medium CEO Ev Williams announced a number of new features for the publishing service, but the one that interests me the most is of course the debut of a new publishing API. The “API” for any publishing service is a sort of interface for 3rd party apps that allows the content of a blog to be read, amended and edited outside of the service’s own web interface. Without an API, a desktop editor like MarsEdit cannot connect to and edit a blog’s posts.

Support for APIs used to be very strong not only for blog publishing services, but for photo sites like Flickr, and micro-blogging sites like Twitter. That enthusiasm seems to have waned in recent years. Popular publishing services such as WordPress, Blogger, and Tumblr still support relatively robust APIs, while Squarespace completely abandoned their API, and Medium has kept us on pins and needles, until now, as to whether they would ever support one.

The new API, which is well-documented on GitHub, seems off to a good start. It’s a REST based design that shares some design similarities with Tumblr’s and Blogger’s APIs. There are also some interesting decisions that set the API apart from any others I’ve seen. Here I present my impressions based on a short tour of the API documentation, and a bit of tinkering with it at the command line.

Authentication

The API supports authentication by way of the relatively standard OAuth2 web-based scheme, through which users are able to authorize a client without ever providing their password. In addition, it supports a “self-issued token” solution through which a user can obtain a token on Medium.com that a client app or service can then use to directly access their Medium content. Currently, Medium is limiting access to the full OAuth based system, so anybody who wants to play around with the API will need to do so using a self-issued token.

License & Attribution

One of the most unique aspects to Medium’s API is the provision for specifying a canonical URL and license on a post being submitted to the service. The canonical URL refers to another web location that should be considered the original, or most authoritative version of a post, while the license designates whether the post’s copyright terms stipulate a post is sharable as public domain or under a particular Creative Commons license. These attributes together indicate that Medium expects and encourages users of the API to contribute content that is not intended to be exclusive to Medium.

As a blogging enthusiast, I like the presence of these attributes because it implies support for a broad range of API client uses, and also because it acknowledges the value of diversity of web content. One of the criticisms of Medium over the past couple years has been the extent to which it encourages writers to abandon their own custom domain names in favor of a proprietary Medium.com based soapbox. These attributes encourage writers who favor their own canonical web sites to nonetheless engage in Medium’s network of readers, writers, and commenters.

Write-Only

The extent to which the API supports working with posts boils down to a single mechanism for submitting a post to the service. It’s not possible to enumerate the list of existing drafts or published posts, e.g. to crosspost to another service or backup your posts to a local archive.

Because of the REST design for the API, there is a natural improvement that would solve this problem. Currently, Medium supports POST access to add a new entry to the collection of posts:

POST /v1/users/<userID>/posts

A typical REST based API for managing assets would also support GET access to this same URL, to facilitate reading the list of existing posts.

Write-Once

Unfortunately, the interface also does not support amending the contents of any post that has been published. So, for example, if you’ve discovered moments after publishing that you left a nagging typo, or got a link wrong (it happens all the time), the API offers no capacity to redo the submission, replacing the contents of the post with updated values. Again, REST conventions have the roadmap for this functionality pretty clearly outlined: while a POST request is typically used to add a new post to a collection, a PUT request to a specific post’s resource URL should be interpreted as updating its content.

Markdown Support-ish

A welcome feature for Markdown fans is the option through the API to specify that the post’s content should be interpreted as either HTML or Markdown formatted text. As far as I know, Markdown is not supported in Medium’s web-based interface, so this may be the debut of “official support” for Markdown on Medium.

Unfortunately, the Markdown support through the API seems to be a one-time conversion from Markdown to HTML, at the time of submission. This means users can write in Markdown for the initial composition of a post, but any further edits (through the web interface only, see above) will need to be done using Medium’s default rich WYSIWYG editor.

A more attractive long-term solution for Markdown fans would be to support storing Markdown text literally in Medium’s database, and converting it to HTML only for presentation on the web. This leaves the pristine Markdown available for perpetual edits either moments or years after the post is first published. This would require updating the web interface to support editing content as plain text, but would be a welcome change for anybody who favors editing in Markdown.

Image Uploads

The API exposes a mechanism for uploading images, but permission to use this aspect of the API will be granted by Medium on a case-by-case basis to applications that Medium deems suitable. This means that for self-issued tokens, image uploads are not possible.

Because I’m using a self-issued token for the time being, I wasn’t able to test this aspect of the API, but it looks relatively straightforward. I appreciate that they support a variety of image formats, including animated GIF, and even TIFF. I have to wonder if at least the TIFF files will be converted to PNG or something more web-friendly.

In response to an image upload, the API vends clients a URL and MD5 hash of the image so that a client could take care to reuse an existing resource rather than upload it again. This is a nice touch, but it would be aided by also supporting a mechanism for listing all the existing images on the blog. Again, using the conventions of a REST API for collection data, a GET against the images URL could do the trick to vend a paged list of existing resources.

In any case, the support for image uploads is very welcome, especially in comparison with Tumblr’s long-standing, nonsensical omission of a similar API mechanism for arbitrary image uploads.

Entitled

The API has a funny caveat about the “title” attribute supplied for a post:

Note that this title is used for SEO and when rendering the post as a listing, but will not appear in the actual post—for that it must be specified in the content field as well.

This leaves client developers is an awkward position where they will need to muck around the user’s content in order to obtain the (likely) desired outcome that a post should show its own title. When I write a new post in Medium’s web-based editor, the title I type into the Title field is respected and sticks with the post as a bona fide title. Through the API however the title must be snuck into the content of the post. It would be better, in my opinion, if the API designated a more fail-safe mechanism for ensuring that a specific title is used as a visible title heading for a post.

A Good Start

My interest in the new Medium API is obviously based in my hope to support the service from MarsEdit. The current limitations, particularly with respect to listing or existing posts, would make it difficult to support Medium at the same level of functionality as other publishing systems. I’m encouraged by the progress though, and am hopeful that in response to feedback from myself and others, they will continue to develop the API into a truly first-class experience for a wide range of 3rd party solutions.

This entry was posted to Links, MarsEdit. Comments are closed. Thanks for reading!