Medium’s New API

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.

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.

POST /v1/users/<userID>/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.

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.

Entitled

The API has a funny caveat about the “title” attribute supplied 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.

--

--

Chief Punkass, Red Sweater Software

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store