32
Greetings from Mailjet Developer Evangelist / Beard - / [email protected] @4thfloor_monkey Find the slides at : evangelistsbarcamp.herokuapp.com

Documenting Your API

  • Upload
    mailjet

  • View
    290

  • Download
    1

Embed Size (px)

Citation preview

Greetings from MailjetDeveloper Evangelist / Beard - / [email protected] @4thfloor_monkey

Find the slides at : evangelistsbarcamp.herokuapp.com

Who are Mailjet?

The Rise and Rise of the APIThat's why we're all here...?

We've got one tooIt's the core of what we do

Everything is built on top of it.

We are drinking our own champagne!

Why is it so important?It offers flexibilityIt adds value to other companies products

Anybody integrated Skype with anything recently?

Developer ExperienceFirst step... 'onboarding'

The ideal onboardingexperience should be:

QuickEasyDevelopers should see immediate value in the service

What helps?Code libraries / pluginsSample code or apps

What obstacles are there toovercome?

Technical Debt from changing systems

Whether the API fits the product and has all the needed functionality

So Documentation is important

Difficult documentation can sink a good productI'm sure you all have pet hates...

Good documentation and a good product make a GREAT product

Getting documentation rightBecause everyone loves collaboration

What did we look at?

Jekyll

Built on RubySupport for templating, plugins and Ruby fun

Thoughts:We liked it, it's pretty neat!Doesn't have strong opinions on styling or implementationThis is both good and bad... like everything!

Swagger

Thoughts:Allows you to directly test calls in the interfaceLoads of community language integrationsGreat for 'sandboxing', not as quick for documentation

Lots of information about the api calls, but a little hidden

So perhaps not for us.

Readme.io

DaaS - Documentation as a service?

Thoughts:Looks niceAims to simplify and save you timeThere are costs involvedNot quite as flexible as rolling your own

We went with Slate

More Ruby based fun!

It's great!Inspired by the Stripe & Braintree documentation

Efficient layoutQuick to generateOpen SourceHighly customisable

It gives you:An index of endpoints and space for explanationsCode required for the callResponse from the server

These are three things I definitely like to find in docs!

How does our documentationwork?

metadata.jsonA nifty code generator

An introduction to JSON Schemahttps://brandur.org/elegant-apis

{"IsReadOnly": false,"Name": "listrecipient","Properties": [ { "DataType": "TContact", "DefaultValue": "", "Description": "Reference to contact which is suscribed to the contactslist.", "IsRequired": true, "Name": "Contact", "ReadOnly": true }, { "DataType": "Int64", "DefaultValue": "", "Description": "Unique numerical ID for this object.", "IsRequired": false, "Name": "ID", "ReadOnly": true },

What are our aims?Consistency and predictabilitySpeed of updating when the API updatesEase of contributions

Disadvantages?Documenting your documentation

AdvantagesTime with the community!

Documentation less likely to stagnategit diff is a wonderful thingFully integrated into Github workflow, with PR's and forksIntegrate update alerts on platforms like Slack to keep you on yourtoes

Questions for the group:What have you found to be your biggest documentation challenges?Which changes have affected API adoption?

To the pub!