Greetings from Mailjet

Greetings from Mailjet

Developer Evangelist / Beard - tsims@mailjet.com / @4thfloor_monkey

Find the slides at : digitalcroydon.herokuapp.com

Who are Mailjet?

The Rise and Rise of the API

Think of the APIs we use all the time (well if you're me anyway)

• Facebook is everywhere
• Foursquare via Citymapper
• Google Maps

We've got one too

It'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 flexibility
• It adds value to other companies products

Anybody integrated Skype with anything recently?

Developer Experience

First step... 'onboarding'

The ideal onboarding experience should be:

• Quick
• Easy
• Developers should see immediate value in the service

What helps?

• Code libraries / plugins
• Sample code or apps

What obstacles are there to overcome?

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 product

I'm sure you all have pet hates...

Good documentation and a good product make a GREAT product

Getting documentation right

Because everyone loves collaboration

What did we look at?

Jekyll

Thoughts:

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

Swagger

Thoughts:

• Allows you to directly test calls in the interface
• No three column layout
• Great for 'sandboxing', not as quick for documentation

Lots of information, but a little hidden

So perhaps not for us.

Readme.io

Thoughts:

• Expensive
• Not quite as flexible as we'd like

We went with Slate

It's great!

Inspired by the Stripe & Braintree documentation

• Efficient layout
• Quick to generate
• Open Source
• Highly customisable

It gives you:

• An index or list of endpoints
• Code required for the call
• Response from the server

How does our documentation work?

• metadata.json
• A nifty code generator

https://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
    },
							
					

A little demo...

What are our aims?

• Consistency and predictability
• Speed of updating when the API changes
• Ease of contributions

Disadvantages?

Documenting your documentation

You might have to answer a few questions on how the generation works

*see above...

Advantages

Time with the community!

• Documentation less likely to stagnate
• git diff is a wonderful thing
• Fully integrated into Github workflow, with PR's and forks
• Integrate update alerts on platforms like Slack to keep you on your toes

Conclusion

- The more open your documentation is, the better -

Free stuff for you!

Use this code when you sign up:

DIGITALCROYDON2015

3 months free Bronze Premium

To the pub!

Or if you have any questions....?