Meta data API for National Library of Finland project getting shape

digiapi-screen

During the previous API Jams a punch of Design-First enthusiasts prepared the path for this project. We have used API Model Canvas for business model development with startup MVP approach. Our ‘customer’ Tuula from National Library of Finland found this approach really valuable. The story of API Model Canvas in this project can be from previous posts.

Background

The API of relates to the strategy of the National Library of Finland (NLF), where openness is one of the corner stones. In addition the Open National Library policy (under work) and Digital Humanism policy include openness and interfaces for the key services as a main targets for the years ahead.

In addition for the modern user, API is needed in order for the user to find their own ways how to utilize the cultural heritage material. API enables connecting different services and maybe even creation of new kinds of services and products.

Project aims

Projecut is APIOps joint project to collaborately design API for the National Library of Finland. Aim is to:

  • define API Model Canvas or two for the case and
  • provide Swagger 2.0 based descriptions for the APIs and
  • mockup servers for prototyping
  • organize larger API Jam during spring 2016

Of course for APIOPS as a whole, one aim is to learn by doing.

Weekend time

Project is classical open source project. People participate as often and as much as they wish. Fluxuating participation requires us to keep timetables flexible. Much of the work is done in API Jams once a month. We all have day jobs which take time and thus much of the in-between of the Jams works takes place during weekends. We have some milestones planned to have short term goals to aim:

  • 6.2.2016: APIOps Monthly Jam to evaluate API Design.
  • 20.2.2016: Get and describe first developer use case
  • 6.3.2016: APIOps Monthly Jam: Finalize MVP version of API Model Canvas & Finalize Design of MVP API
  • 2.4.2016: APIOps Monthly Jam: Implement good enough mockup responses and launch API in Heroku
  • 17.5.2016: Suggest APIOps Jam in API Days 2016 in Tampere. Get ideas for API usage and get developer feedback.
  • 1.6.2016: Package all for ‘sales’ so that Tuula can show it to management of National Library of Finland.

Development process getting shape

During this weekend I had Saturday afternoon and Sunday morning time for this project. I focused on API Design first. So far we have used publicly available Swagger editors. One of the editors is running in http://swaggereditor.digipalvelutehdas.fi/

It’s a nice tool but problem is that you can not save your work. In other words, you keep separate copy of the API spec in some place and then upload the file to editor. In my opinion, these non-saving editors are good places to fool around and get first touch to editors. We needed more, we needed more simple and automated development process.

Node, Git, Swagger module and Github

Swagger is known to have enormous amount of open source tools. We are already using Github as hub for all code, designs and documentation. Therefore it makes sense to utilize Github and extend our development process around it. I decided to try swagger tools and node. Node was selected since Swagger codegenerator is able to use that as target platform and because other team members felt prone towards it.

API Design tools and Mockup server in one package

One of project aims is to create mockup API. This constantly updated mockup server is for developers of the spec and for others to test API locally. Server will be used until we (developers/API -consumers/customer) are happy with the design. After that backend connections are created. You can run the API locally and develop API Swagger 2.0 spec with ready-made tools.

In our approach swagger spec lives inside project generated with Swagger node module. This project is inside git project, which is managed in Github. Package contains Swagger editor which can be launched locally with simple command ‘swagger project edit’. It opens Swagger editor to browser. The benefit compared to using for example http://swaggereditor.digipalvelutehdas.fi/ is that al changes are saved in local file ‘app/swagger/swagger.yaml’.

Developer can easily launch mockup API with the same tools with command: ‘swagger project start -m’. After that API can be tested with curl and from browser.

There you have it: API Design tools and Mockup server in one package.

All developer needs to do is, clone repository, install a few applications. More details about the developer package can be found from project home https://github.com/APIOps/Digiapi/tree/master/node-mockup-api

Project management

We have divided roles for participants so far. That enables each of us to focus on some area and make sure we don’t do overlapping work. All the feature request and issues are handled in Github. Yet, planning work and following progress is pain in Github. Therefore we decided to use waffle.io https://waffle.io/APIOps/Digiapi. Of course Trello could have been an option too. Overall view to project can be viewed in Github project repository (https://github.com/APIOps/Digiapi). Big decisions are made in API Jams. Tasks are devided to participants at the end of API Jam. If someone is not able to do their tasks, it’s not the end of the world.

Feel free to join us. Check out Github home. We especially need more API consumers aka developers who would be using API.

You are the rock star, you are the one we are building this API for.