How we have developed our API using RAML, JSON and agile methods. How API helps business people and developers speak same language.

1. Homo Apitus
WHY EVERYONE SPEAKING “APISH” MAKES YOUR
WHOLE BUSINESS MORE AGILE?
By Marjukka Niinioja and all the great characters at PlanMill Oy

2. ABOUT ME
Marjukka Niinioja @Mniinioja
Senior Consultant & Manager
PlanMill Oy @PlanMill
www.planmill.com
Working with software
development and integrations
since 2000
Work experience from
government, adult education
and private sector.
Master of Education, minoring
in Leadership and Computer
Science.
Check out our API at:
http://api-portal.
anypoint.mulesoft.com/pl
anmill/api/planmill-rest-api-15
Read about why we chose RAML
http://apisuomi.fi/2014/10/rest
-raml/

3. PLANMILL IS A WEB BASED ERP, PROJECT AND CRM
SOFTWARE
Customizable, Cloud, On-premise – been used since 2001 by 100+ customers in Finland, Europe
and overseas

4. 25+
COUNTRIES
100+
CUSTOMERS
20 000+
USERS
13
YRS IN BUSINESS
25
SKILLED EXPERTS
2 000+
NET SALES (T€)
PLANMILL TODAY
SALES PROJECTS TIME
EXPENSES REQUESTS
FINANCES
Our customers are the future makers and shakers. They are leading the way in
their fields of expertise pushing the boundaries into new levels.
Connected to PlanMill

5. TIME FLIES WHEN YOU
DEVELOP ARCHITECTURE
In-house system
”Nokia Planner”
Commercial
project
management
software
MS SQL Server
based version
1988 1992
First Lotus Domino
database
connector in the
world with IBM
1998
1999
Java applet
based user
interfaces
First WAP-based
time tracking
system in the
world co-developped
with
Nokia
Confluence plugin
with Ambientia
using the API
2004 2006
Atlassian
Java + XML &
XSLT
From project
management to
PSA
2010
Open
API 1.0
Mobile
touch
interface
Expanding from
On-premise to
Cloud
2009
Open
API 1.5
20112014
ERP
integraitng
with lots of
trad. Web
services

6. 2009 – API 1.0 : ”THE ACCIDENTAL
API DEVELOPER REACHES
TODDLER AGE AND LEARNS HOW
TO WALK”
First 12 months
Devs have
an idea
Consultants start
speaking about it
to customers
API is born
API?? What is
that??
Very quiet
launch
”Productization”: Test
environment, API key request
form, usable dev documentation,
some idea of pricing
First real use cases
by customers
around projects and
time reporting
Amount of employees ”on the know”
First big API using
application project
sold, massive
improvements to API
as result
API as major
selling point
compared to
competitors
First partnership case
(Atlassian Confluence
with Ambientia) made
possible by API
”Learning by supporting” ”Learning by coding and co-coding”
http://www.slideshare.net/MarjukkaNiinioja/accidental-api-developer-the-
12-month-period-from-birth-to-toddler-and-beyond

7. 2014: NEW IMPROVED PROCESS
TOWARDS THE API 2.0
Towards the new API
powered ecosystem
Research project
Customer & Partner
needs and insights
Piloting technologies and
preliminary services of
API by parallel
developing client
software
Demos, knowlegde
sharing and discussions
with whole company
Architecture vs. strategy –
what services, how to
maintain, how to
monetize
Internal beta
Teach with the beta
through real projects
Public beta + developer
community
Feedback from developer
community
Publish 1.5
Eat our own dogfood with
your own client using API

8. WHAT LANGUAGES DO YOU
SPEAK?
Finnish Icelandic
Swedish Czech
Danish Java
Norwegian Python
English C++
German Pascal
French JSON
Estonian XML
Greek XHTML

9. BUT ARE WE REALLY TALKING
ABOUT THE SAME THING?
System A
Customer
Company
Person
Decision maker
Lead
Deal
Sales project
System B
/accounts
/contacts
/opportunit
ies

10. “As a project
manager I want to
create new
projects”
public static
createProject(name,st
art)…
CONNECT
/TEAMS?VIA=API
POST /projects {name: “My first project”,
Start: “2014-01-01T00:00:00Z}

11. EVEN A MONKEY COULD
INTEGRATE 2 SYSTEMS
GIVEN ENOUGH TIME…
Old way with integration specific file
formats took minimum of 40-60 hours
per integration:
• 2 workshops with 10 people
• 10-20 emails guessing what customer
and integration partner actually want
to transfer
• 5 hours of guessing formats
• 10 hours of guessing what the fields
mean
• 15 hours of debugging when you
finally get to test
• 20+ hours of figuring out what random
undocumented error messages mean
after integration went to production
The infinite monkey
theorem states that a monkey
hitting keys at random on
a typewriter keyboard for an
infinite amount of time
will almost surely type a given
text, such as the complete works
of William Shakespeare.
Source:
http://en.wikipedia.org/wiki/Infi
nite_monkey_theorem

12. GET /CUSTOMERS
GET /PARTNERS
Renewing our system API
first has given as an
opportunity to use our
customers as our “co-developers”.
They are building apps
for themselves and
sharing ideas and
helping us to get ideas
what we should
incorporate in our
product.
Typical bigger API-based integration
project takes 2-10 hours of our or
customer’s time

13. API CHANGED THE WAY WE
WORK
TRAD: ”I’m selling an application – look how I demo by
clicking the UI”
API: ”I’m selling a application with API – look how quickly
I can get some data out or develop this app”
TRAD: ”Customer was asking for help using the system –
I asked her for screen shots”
API: ”I asked the customer to send info about the API
requests and responses he was trying to use”

14. APES IN SPACE – ARE YOU
CRAZY?

15. LEARNING A NEW WAY OF
THINKING…
API is something only ”techies”
and only ”some API techies”
should know about
API is separate from the ”actual”
system
New features and changes can be
implemented without ever
thinking of API
API is going to be used so little
that we don’t need to think about
traffic limits or pricing models
Using API to automate testing of
the system is difficult
API doesn’t need user
documentation
It’s ok to expose our internal
data model ”as is” to outside
world
All users of the same API in the
same instance can see all data
”Open information” vs.
”Restricted information” in a
business application – all data
should be accessed by any API
user
API is only going to be used by
”outsiders”

16. PRESUMPTIONS IS THE MOTHER OF
ALL…
It was presumed that our
backend couldn’t
support a great new
JSON state of the art
API… and a lot of other
things…
But then we decided
together:
Let’s make our process
faster, better, bug free,
and renew our
application one step at a
time – starting with API!
Buttons as embodiment of our strategy
created in our staff day in 05/2014

17. POST /VISION?TYPE=SHARED
Joint understanding based on results and issues from previous
sprints and hands-on research tasks helped to speed up team
work.

18. GET
/VOCABULARY?
TYPE=SAME
Discussing
Educating
Organizing and
participating in meetings
and seminars
Inviting students from
polytechnics as research
buddies and mentors
Understanding strengths
and weaknesses of our
current system and API
If people don’t understand what API is
about, they won’t tell about it, sell it,
use it, develop it or support it

19. GET
/RESEARCH
During Spring 2014 we
created pilot application
with really new
technologies to understand
the possibilities better and
to see what we can use
along our current system.
Pilot was built using
Jackson + Hibernate +
Drools + AngularJS 1 app /
1 business module pilot to
see how to replace our Java
+ XSL + MS SQL 20 module
system.

20. HARDEST PART OF CREATING A
BACKLOG WAS TO ELIMINATE THE
“UNKNOWN” AND TO ACCEPT THAT
PLANS CAN CHANGE
Team estimated how many hours they would have
for the next 2 week sprint and created backlog
items and estimated them roughly. New API was
developed in 6 2-week sprints.

21. WHY WE CHOSE RAML AS JOINT SPECIFICATION
RAML is a new standard for writing API specifications. It has a documented syntax
and lot’s of good tools. It helped our team, to speak the same “language” in
designing the API endpoints, error messages and content. It was understandable by
both UI and backend teams.
Read about why we chose RAML:
http://apisuomi.fi/2014/10/rest-raml/

22. AND SUDDENLY THERE WERE
TESTS…
Integration tests with
RESTAssured
UI tests with
Thucydides and JBehave

23. THANK YOU!
Marjukka Niinioja @Mniinioja
Senior Consultant & Manager
PlanMill Oy @PlanMill
www.planmill.com
Check out our API at:
http://api-portal.
anypoint.mulesoft.com/
planmill/api/planmill-rest-api-
15