To build my first API, I will use a design first approach.
Why design first ?
My background as a software architect leads me naturally to opt for a design first approach.
I googled a little bit to confirm that the design first approach still applies in an Agile and API world (we never know) :
- Excellent presentation from Jason Harmon or similar on slideshare
- API Evangelist
- apigee
Use case
The use case that will be used for the first API will be based on a flash word learning technic that is used for kids with dyslexia. For the first API, I will only build an API that allows to do CRUD operation on a word list:
- Create, Update or Delete a word list.
- Get a word list.
I know the operations are rather basic for now, but I want to start small and I’ll add more later.
Tools
I’ll use the Swagger format to design the API and store it on Swagger Hub.
Designing the API
The swagger editor is nice but it doesn’t help in creating a valid YAML document. To create my API, I add to go to the OPENAPI SPECIFICATION reference page and I refered to another example that a had written last year to test the swagger specification.
Designing the entities
I started by defining my entities required for my API.
Reusable parameters
I have the wordListID parameter that is used in a few places so I created a parameter for that.
Create the required verbs
The final step was to create the verbs required to implement my API.
The API
You can explore the complete Words API on swaggerHub.
Intuitive and easy
This first step was easy to do and I the swagger format helped me in designing a simple and clear API to be used.