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?
First step... 'onboarding'
The ideal onboarding experience should be:
- Developers should see immediate value in the service
- 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
- We liked it, it's pretty neat!
- Doesn't have strong opinions on styling
- This is both good and bad... like everything!
- 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.
- Not quite as flexible as we'd like
We went with Slate
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
"Description": "Reference to contact which is suscribed to the contactslist.",
"Description": "Unique numerical ID for this object.",
A little demo...
What are our aims?
- Consistency and predictability
- Speed of updating when the API changes
- Ease of contributions
Documenting your documentation
You might have to answer a few questions on how the generation works
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
- The more open your documentation is, the better -
Free stuff for you!
Use this code when you sign up:
3 months free Bronze Premium
To the pub!
Or if you have any questions....?