amzani / api-deep-dive

Deep dive workshop

API Design Workshop

Requirements

• Read Adidas API Guidelines
• Git
• Code editor (e.g. VS Code)
  • in case you are using VS Code, install extensions such as openapi-lint and YAML
• Swaggerhub account within adidas group (create an account and request access to it)
• Spectral for local and ci/cd validations.

Design challenge

As a new assignment you are asked to write an API contract basing on a given list of affordances. You will base on a sample api description following adidas API guidelines and a number of predefined object models.

Your team decided wisely to think API First and API Design First.

API affordances (actions)

The existing core Product API provides this affordances:

• Retrieve the list of products
• Retrieve a single product
• Retrieve the metadata related to products (tags, status, categories)
• Create a product
• Update an existing product (status...)
• Retrieve reviews about a product
• Add a product review
• Retrieve product reviews statistics
• Create a user
• Retrieve user profile
• Retrieve the user wishlist
• Add a product into the wishlist
• Delete a specific product from the wishlist
• Clear the wishlist

Step1. Let's describe what actions our API affords

TASK: Translate the affordances into a REST API model. What endpoints will this API have? What operations will it perform on these endpoints? Can you find an alternative way to achieve similar, if not better, results from a design point of view?

Step2. Formalize the design in the Open API Specification

The OAS (Open API Specification) file can be edited in whatever tool you like BUT NOT GENERATED FROM YOUR CODE. We suggest either using the internal editor in Swaggerhub or VS Code with extensions. The most important thing is that the final one (the contract) MUST be in Swaggerhub.

TASK: Extend the existing sample-api.yaml. First change the filename into a name of your project.

We will walk step by step through the file explaining each of the different elements. Then basing on them you will, in pairs, complete a list of exercises defining subsequent parts of the API contract.

NOTE: Remember to validate your API specification after each exercise (step) completed.

Step3. Verify the design using Swaggerhub Documentation and Swaggerhub Auto-Mocking Service

TASK: Put your API contract into a new Swaggerhub API under a project. Put models in a Domain in Swaggerhub. Reference the models from the domain in your API. Check the validation. Does your API comply with the rules? If yes, try the Apiary Mock Service.

Step4. Review the API Design

At this stage you:

• Ask feedback from your API users by sending them the documentation link.
• Ask feedback from your product owner

In our context it means that you will change your pairs and in those new pairs verify each other's design (peer review).

Some example of bad designed APIs

[Sales and Distribution] Returns Confirmation API

Missing description Missing examples Missing HAL Exposing internal model Missing support contact

ATP Notification Service

Usage of acronyms, what's ATP stands for ? Missing description / context Missing HAL Missing support contact

Some example of good designed APIs

Sample APIs following the guidelines are available at adidas-group GitHub. The samples include the following:

Simple API

Very simple API including implementation, testing, and full CI/CD lifecycle.

Approval API

Real-world API with state transition, API key client app authentication, exposed via API management.

Orders API

Sample API used as the template for newly created projects at Apiary.

Inventory API

Real-world Adidas Inventory API (WIP)

Appointment Service

Demo API, including implementation and testing used during training.

Complex Search Parameters

Sample API showcasing description of complex query parameter rules.

[CPM] Asset Trafficker https://assetmanager4.docs.apiary.io/