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
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?
The ideal onboardingexperience should be:
QuickEasyDevelopers should see immediate value in the service
What obstacles are there toovercome?
Technical Debt from changing systems
Whether the API fits the product and has all the needed functionality
Difficult documentation can sink a good productI'm sure you all have pet hates...
Good documentation and a good product make a GREAT product
Thoughts:We liked it, it's pretty neat!Doesn't have strong opinions on styling or implementationThis is both good and bad... like everything!
Thoughts:Allows you to directly test calls in the interfaceLoads of community language integrationsGreat for 'sandboxing', not as quick for documentation
Thoughts:Looks niceAims to simplify and save you timeThere are costs involvedNot quite as flexible as rolling your own
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
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?