How to transfer from legacy system and legacy company to the brave new API world?
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

How to transfer from legacy system and legacy company to the brave new API world?

on

  • 501 views

"From Legacy to a Brave New API World" - PlanMill Ltd tells story of how their API was born held the Nordic API event in Helsinki on 2.4.2014

"From Legacy to a Brave New API World" - PlanMill Ltd tells story of how their API was born held the Nordic API event in Helsinki on 2.4.2014

Statistics

Views

Total Views
501
Views on SlideShare
501
Embed Views
0

Actions

Likes
1
Downloads
1
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

How to transfer from legacy system and legacy company to the brave new API world? Presentation Transcript

  • 1. Accelerating Your SuccessAccelerating Your Success PLANMILL API 2.0 7.2.2014 TERVETULOA!
  • 2. Accelerating Your SuccessAccelerating Your Success PlanMill API 2.0 OHJELMA 13.45 Ilmoittautuminen & kahvi 14.00 Tilaisuuden avaus 14.20 Case Ambientia & Futurice 15.00 Round Table: Mihin API:a käytetään? 15.30 PlanMill API 2.0 tavoitteet 16.00 Yhteenveto 16.15 Keskustelu & verkostoitumista 18.00 Tilaisuus päättyy 4.4.2014 2© 2013 PlanMill Ltd. I www.planmill.com PUHUJAT • PlanMill: Marjukka Niinioja • Ambientia: Henri Sora • Futurice: Mats Malmsten
  • 3. Accelerating Your SuccessAccelerating Your Success PLANMILL TODAY 4.4.2014 3© 2014 PlanMill Ltd. I www.planmill.com
  • 4. Accelerating Your SuccessAccelerating Your Success PLANMILL IN BRIEF 4.4.2014 4© 2014 PlanMill Ltd. I www.planmill.com 25+ COUNTRIES 100+ CUSTOMERS 20 000+ USERS 13 YRS IN BUSINESS 25 SKILLED EXPERTS 2 000+ NET SALES (T€)
  • 5. Accelerating Your SuccessAccelerating Your Success PlanMill API energizes the ecosystem Acquire customers via network effects, and address larger businesses Expert talented team and support Open reliable API on with which to grow your business Smiling mutual customers that don’t churn 10 and growing network of SaaS partners added PlanMill’s wall of innovation No fees and strong SaaS network 4.4.2014 5© 2014 PlanMill Ltd. I www.planmill.com
  • 6. Accelerating Your SuccessAccelerating Your Success PLANMILL SOLUTON IN BRIEF API 1.0 since 2010 4.4.2014 6© 2014 PlanMill Ltd. I www.planmill.com SALES EXPENSES REQUESTS PROJECTS TIME FINANCES
  • 7. Accelerating Your SuccessAccelerating Your Success Our customers are the future makers and shakers. They are leading the way in their fields of expertise pushing the boundaries into new levels. OUR CUSTOMERS LEAD THE WAY 7© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 8. Accelerating Your SuccessAccelerating Your Success Statistics from our current API (2 months) 8© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 9. Accelerating Your SuccessAccelerating Your Success API cases: GIA white paper download based lead qualification
  • 10. Accelerating Your SuccessAccelerating Your Success
  • 11. Accelerating Your SuccessAccelerating Your Success What is a REST API? Standardard protocol for communication between internet based systems but not a standard for the content • Like ”A4” paper = standard size • Content of the paper can be anything: advertisement, job application, invoice, tax form etc… • Standard responses, like when you send a registered letter: • ”OK – letter was delivered” • Address correct but the person not: ”ERROR – recipient not found in this address” • If you send a tax form but you have not filled all the fields, you get: ”ERROR – form had errors” 11© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 12. Accelerating Your SuccessAccelerating Your Success REST API definition • With RESTful APIs and RESTful Web Services, clients use basic HTTP verbs (GET, POST, PUT, DELETE) • In these APIs, the remote information objects are identified with URLs • RESTful APIs can be defined independent of the formats used for conveying the state of the objects; typically services use custom XML and/or JSON encodings of state information. • (http://www.w3.org/2012/ldp/charter, http://en.wikipedia.org/wiki/Repre sentational_state_transfer) 12© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 13. Accelerating Your SuccessAccelerating Your Success http://martinfowler.com/articles/richardsonMaturityModel.html https://planmill.com/{customerInstance}/api/{version} /salesorders (collection i.e. multiple sales orders /salesorders/123 (one sales order with id 123) GET /salesorders DELETE /salesorders/123 <link rel = "/linkrels/salesorders/setOrdered" uri = "/salesorders/123"/> 13© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 14. Accelerating Your SuccessAccelerating Your Success PlanMill API - TODAY Project is created in PlanMill Application X https://online.planmill.com/acme/services/rest?method=proj ect.insert&format=rest&PMVProject.Name=”Example%20proj ect” &PMVProject.Type = ”3”… https://server/instance/services/rest?method=account.get&format=rest&userid=12345 &authkey=531adbb3022a96e537b4e2a5289e128e Project type is updated in PlanMill https://online.planmill.com/acme/services/rest?method=proj ect.update&format=rest&PMVProject.Id = 123&PMVProject.Type = ”2”… https://online.planmill.com/acme/services/rest?method=proj ect.delete&format=rest&PMVProject.Id = 123 Project is deleted from PlanMill 14© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 15. Accelerating Your SuccessAccelerating Your Success CASE AMBIENTIA 4.4.2014 15© 2014 PlanMill Ltd. I www.planmill.com
  • 16. Accelerating Your SuccessAccelerating Your Success CASE FUTURICE 4.4.2014 16© 2014 PlanMill Ltd. I www.planmill.com
  • 17. Accelerating Your SuccessAccelerating Your Success ROUND TABLE 4.4.2014 17© 2014 PlanMill Ltd. I www.planmill.com
  • 18. Accelerating Your SuccessAccelerating Your Success SUMMARY 4.4.2014 18© 2014 PlanMill Ltd. I www.planmill.com
  • 19. Accelerating Your SuccessAccelerating Your Success Q & A’s 4.4.2014 19© 2014 PlanMill Ltd. I www.planmill.com
  • 20. Accelerating Your SuccessAccelerating Your Success Current architecture Customer Database Shared Database (All default parameters) Java application Database views Some business logic and all system parameters Desktop web client Mobile web client REST APIExportImport UI parameters Mobile UI parameters Export parameters Import parameters Reports Report parameters Email Integrator Services f.eg.: Jobs (like unix cron) Data mapping Validation and other business rules UI formatting & javascript XSL -> XHTML, PDF, API XML etc. DB query results to XML through business classes 20© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 21. Accelerating Your SuccessAccelerating Your Success Separation of concerns 1/2 CSS: Colors, fonts Device specific UI Layout of the page Locale specific fields like business id, vat registration Locale specific formating of fields like dates, numbers, currencies Locale specific translations of display names for fields and field values Customized fields Validation rules for fields: is order date required when status is cancelled? Is 31.3.2014 valid date? Product and role based resources available 21© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 22. Accelerating Your SuccessAccelerating Your Success Separation of concerns 2/2 Validation rules for fields: is order date required when status is cancelled? Is 31.3.2014 valid date? Locale specific translations of display names for fields and field values Locale specific formating of fields like dates, numbers, currencies Interface declaration for sales order object (binding between DB fields, backend Java and front end Business rules and field validations need to stay the same with all clients: Desktop, mobile, direct REST API calls, imports, exports etc. 22© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 23. Accelerating Your SuccessAccelerating Your Success ”Non-REST” integration formats SEPA - Single European Payment Area (XML) • Coming Q2/2014 – used for transferring expense payment data from PlanMill to banking software https://www.fkl.fi/en/themes/sepa/sepa_documents/Pages/default.aspx • Each bank has separate web service for transferring these, should we make a REST API request available for transferring the XML files? Finvoice (standard for electronic invoicing in Finland) • Current version 1.2, version 1.3 available as default from 03/2014 • No plans yet for 2.x versions (SEPA direct debit related) but improved versioning support coming during 2014 • Current API supports fetching invoices in XML form Partner specific web services currently available • Administer (eFina), Netvisor, Maventa, Basware, Atlassian Crowd – future of these? Webhooks? • http://timothyfitz.com/2009/02/09/what-webhooks-are-and-why-you-should-care/ • http://progrium.com/blog/2012/11/19/from-webhooks-to-the-evented-web/ • https://www.webscript.io/ 23© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 24. Accelerating Your SuccessAccelerating Your Success PLANMILL API 2.0 KEY GOALS 4.4.2014 24© 2014 PlanMill Ltd. I www.planmill.com
  • 25. Accelerating Your SuccessAccelerating Your Success Why API 2.0? • Easier adoption: – Anyone with any experience with HTTP, XML, JSON and other RESTful APIs can understand and use our API in minutes – Plug and play with ready-made application frameworks and tools • Ecosystem with customers, partners and public data sources • Faster, easier and less risky product development and customized development and integration – shorter time to market • Solid base with common business logic and data validation for all output and input formats, applications and devices (= end points) 25© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 26. Accelerating Your SuccessAccelerating Your Success Create an API which is founded on industry best practices • Easy to use, maintain and well documented (with examples) • Testable • Supporting ready-made libraries and tools for developing clients which consume the API as well as linking the API to the backend • Secure • Stateless & fast • Possible to monitor, trouble shoot and have metrics • Possible to have traffic limitations • Specifically formatting or not formatting request and response data according to locale and formatting • Support customized data fields and customized validation rules • Support building of a new single-page PlanMill application and user interface 26© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 27. Accelerating Your SuccessAccelerating Your Success Discover use cases which are needed to be supported • CRUD: Create, read, update, delete resources – Resource = business object like individual sales order, also "patch" updates could be supported • Listing multiple resources (=collection) • Getting information about a single resource and its linked (=embedded) objects – Sales order, sales order items, persons who modified it, file attachments linked to it, emails linked to it, project linked to it etc. • Reporting, importing and exporting data – Bulk data inserts, updates, deletes and gets, pre-calculated indicators like utilization %, profitability etc. • Extras to help UI and other client development – Enumeration (= list values) and other data labels in requested language – locale spesific formatting – service configuration: enabling or changing integrations, add-ons, customizations etc. 27© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 28. Accelerating Your SuccessAccelerating Your Success Establish a process for designing, documenting, versioning and maintaining the API 1. Create / update specification 2. Test modified specification with mock service 3. Change advisory board (CAB acceptance for the changes) 4. Create permanent example use cases from the test cases (including example data, requests, responses and comments) 5. Publish specification, tests and examples in a public site (developers.planmill.com/raml, http://www.apihub.com/planmill/api/planmill-openapi-20 and version controlling f. ex. GitHub) so customers, partners etc. can get access to them 6. Publish the new version of the specification and examples for the community using the API (early warning to give time for feedback and changes) 7. Generate the Java code from the specification to JAX-RS (or other) classes to bind he API requests and responses to the backend 8. Run integration and regression tests 9. Merge with trunk 10. Inform all API users (internal and external) 11. Release 12. Publish API and inform all API users 28© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 29. Accelerating Your SuccessAccelerating Your Success Making it easier for users of API • Currently not standard authentication and API key discovery, needs to be improved • Documentation • Examples with example code • Authentication (Basic or Oauth or both) 29© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 30. Accelerating Your SuccessAccelerating Your Success Possible new architecture Customer Database Shared Database (All default parameters) Java application Database views (common business logic) Companies API Responsive web client(s) Device specific client(s) REST API ImportExport Reports System parameters Time report API Projects API SalesOrders API Invoices API Metadata API Webhooks API Email, SMS, Social media, intranet, finance & other 3rd party applications Reporting API pushPre-calculated values organized in time series – including history data of single objects Users can predefine urls to call when a specific pre-defined action happens: ”New project created” - > post to JIRA ”New customer created” -> post to Salesforce ”New invoice created” - > post to eFina 30© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 31. Accelerating Your SuccessAccelerating Your Success IMPLEMENTATION DETAILS 4.4.2014 © 2014 PlanMill Ltd. I www.planmill.com 31
  • 32. Accelerating Your SuccessAccelerating Your Success Research questions and (current) answers • How API specification should be created? – RAML+ Anypoint: RAML is the new open source standard created by industry leaders • How should the requests be built and mapped to the backend? – Jersey (JAX –RS) • What formats should be supported? – JSON and/or XML, for “reporting API” also CSV, Excel, PDF??? • Best practices for formatting data fields in requests and responses? • Authentication? – Basic authentication, OAuth or existing? 32© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 33. Accelerating Your SuccessAccelerating Your Success Comparison of API specs tools Feature Anypoint API Platform Apiary I/O Docs Swagger Enunciate Full services Yes Yes no no no Language for API definition RAML API Blueprint markdown JSON schema Can be handwritten in JSON or generated from code Source code for the API is read, analyzed, and loaded into an abstract form during build-time Documentation generation Yes Yes ? ? ? Resource mocking No Yes Yes Yes Yes Debugging No By listening to requests to mock or to the real API via a proxy ? ? ? Testing Shareable JavaScript snippe ts saved as gists Only editable example tests in the documentation ? ? ? Client code generation Being developed ? Java, PHP with I/O Wrapper JavaScript, Scala, Flash, Java, Objc, PHP, Python, Python3, Ruby C, C#, objC, Java, PHP Other API Portal for developers JAX-RS code generation Specification versioning as gists Interface definition document creation (WSDL, WADL) SOAP endpoint generation Swagger UI generation 33© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 34. Accelerating Your SuccessAccelerating Your Success Content types – does anyone need XML anymore? • The two mainly used content types in APIs are JSON and XML. XML is still the mostly used format but new APIs are more likely to serve JSON instead of XML. Many companies, like Twitter, have decided to drop XML support altogether. – 1 in 5 APIs say "Bye XML" – JSON vs XML • JSON + Native browser support (JavaScript) + Supported by a number of off-the-shelf utilities for working with JSON-formatted data in non- Javascript languages such as Ruby and .NET. + Lower overhead + Formal and concise design, easy to read • XML + Extensibility and the avoidance of namespace clashes + Holds any data type and can be used to transport full documents with formatting information included - Bigger size because of formatting - Parsing takes longer - Usually more complex than necessary for Web Services 34© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 35. Accelerating Your SuccessAccelerating Your Success Tools for testing RESTful services Service Mocks • Betamax is a tool for mocking external HTTP resources such as web services and REST APIs in your tests.It is done by intercepting HTTP connections initiated by your application and replaying previously recorded responses. • WireMock is a flexible library for stubbing and mocking web services. Unlike general purpose mocking tools it works by creating an actual HTTP server that your code under test can connect to as it would a real web service. • Restito is a tool which is inspired by mockito and functionally is diametrically opposite to the Rest Assured. It provides a DSL to mimic rest server behavior, record HTTP calls to the server and to perform verification against happened calls. Client • REST Assured is a Java DSL for simplifying testing of REST based services built on top of HTTP Builder. • Restfuse is a JUnit extension library for automated REST/HTTP integration tests. • Test Driver is used to test RESTful services and clients. © 2014 PlanMill Ltd. I www.planmill.com 354.4.2014
  • 36. Accelerating Your SuccessAccelerating Your Success Binding to backend • Java API for RESTful Web Services (JAX-RS) from Sun/Oracle that provides support in creating web services according to the Representational State Transfer (REST) architectural pattern. JAX-RS uses annotations, introduced in Java SE 5, to simplify the development and deployment of web service clients and endpoints. JAX-RS is an official part of Java EE 6. • Most REST java libraries are based on this API, one notable exception to this being the Restlet Framework. The core of each JAX-RS implementation is the same so the only difference between them are the extra features they provide and it is said that it is possible to change from one JAX-RS implementation to other with minimal effort. • RESTful web services are stateless and widely support caching (Expiry dates, ETags, LastModified) which improves scalability. 36© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 37. Accelerating Your SuccessAccelerating Your Success Current authentication: API Keys Good or bad? • Instead of using the traditional username and password for authentication, an API key can be generated for each user. – API keys/secrets are usually a long series of random characters that are difficult to guess. – Username/password are typically much smaller in length, use common words, are generally insecure, and can be subject to brute force and dictionary attacks. • Passwords can also be reset often. If you use the password as part of your API authentication scheme, API access would fail every time the password is changed. – Currently API keys are generated based on hash from password, so they do change everytime user changes password • Best practices say to encrypt your passwords in the database to limit a potential data breach. This increases overhead for each request when authenticating a user. Unique API keys authentication skips the hashing step and therefore speeds up your calls. – Currently API keys are generated from passwords and passwords are encrypted in db, so this may slow some API calls Should we use API keys also in API 2.0? Should we change them to NOT be dependent on password changes? 37© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 38. Accelerating Your SuccessAccelerating Your Success Basic authentication vs. OAuth • There are a few ways to secure a RESTful API. The easiest would be using Basic HTTP authentication. – implemented by sending the credentials on a header of every request. – The credentials are Base64 encoded but not hashed or encrypted in any way. – Basic authentication is therefore used over HTTPS. • The most secure option would be OAuth 1.0a. – The protocol uses a cryptographic signature, (usually HMAC-SHA1) value that combines the token secret, nonce, and other request based information. – The great advantage of OAuth 1 is you never directly pass the token secret across the wire, which completely eliminates the possibility of anyone seeing a password in transit. – This is the only of the three protocols that can be safely used without SSL (although you should still use SSL if the data transferred is sensitive). • OAuth 2.0 is a completely different take on authentication that attempts to reduce complexity. – Oauth2’s current specification removes signatures, so you no longer need to use cryptographic algorithms to create, generate, and validate signatures. – All the encryption is now handled by TLS, which is required. There are not as many Oauth2 libraries as there are Oauth1a libraries, so integrating this protocol into your API may be more challenging. • The last option is to use a custom authentication. Custom authentication protocols should be avoided unless you really, really know what you are doing and fully understand all the intricacies of cryptographic digital signatures. • JIRA, for example uses a wide range of authentications but recommends using either OAuth 1.0a or HTTP Basic. Twitter uses OAuth 1.0a aswell while Salesforce favors OAuth 2.0. 38© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 39. Accelerating Your SuccessAccelerating Your Success API Designer in Anypoint – Example in RAML 39© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 40. Accelerating Your SuccessAccelerating Your Success API docs in Anypoint
  • 41. Accelerating Your SuccessAccelerating Your Success Example request and response
  • 42. Accelerating Your SuccessAccelerating Your Success Decision time… QUESTION: Sales order type 10 = ”Draft quote”, should we point to enumeration object (with a specific Metadata API) for values in language of the locale or give value directly? % -values with % -symbol or at least divided / 100 or not (YAML or RAML doesn’t tell and both are seen in APIs) Date and time values in RFC2616 ”Sun, 06 Nov 1994 08:49:37 GMT” (RAML specs) What situations require specific errors codes? 42© 2014 PlanMill Ltd. I www.planmill.com4.4.2014
  • 43. Accelerating Your SuccessAccelerating Your Success MORE INFORMATION Marjukka Niinioja & Pasi Härme (Helsinki Metropolia University of Applied Sciences) PlanMill Ltd. Hämeentie 19, FI-00500 Helsinki Tel: +358 10 322 9110 Email: firstname.lastname@planmill.com Website: www.planmill.com
  • 44. Accelerating Your SuccessAccelerating Your Success ”Bedtime reading”
  • 45. Accelerating Your SuccessAccelerating Your Success RESTful specs with RAML resources • http://lj.platformatyourservice.com/wiki/index.php?title=REST_API #Conventions_and_Considerations • http://raml.org/ • http://raml.org/spec.html • http://www.mulesoft.com/mulesoft-advances-api-design-tooling- raml • http://blog.programmableweb.com/2013/10/23/raml-open- specification-and-tools-released-to-aid-in-api-design/ • http://blog.programmableweb.com/2011/11/18/rest-api-design- putting-the-type-in-content-type/ • http://forums.raml.org/t/how-is-this-different-from-swagger/24/4 • https://jersey.java.net/documentation/latest/user-guide.html
  • 46. Accelerating Your SuccessAccelerating Your Success Webhooks and reporting API resources • https://skillsmatter.com/skillscasts/3197-sletten-rest- bdd • http://developers.freshbooks.com/webhooks/ • https://developers.google.com/analytics/devguides/ reporting/metadata/v3/ • https://zohoreportsapi.wiki.zoho.com/ • https://developers.google.com/adwords/api/docs/gu ides/reporting-concepts
  • 47. Accelerating Your SuccessAccelerating Your Success Contact us today! Marjukka Niinioja PlanMill Ltd. Hämeentie 19, FI-00500 Helsinki Tel: +358 10 322 9110 Email: firstname.lastname@planmill.com Website: www.planmill.com Stay Connected