Time estimate: You should be able to complete this basic tutorial in about 20-25 minutes.

Let us begin to explore the MAP language in three steps:

0. Understand the sample API requirements
1. Explore MAP website and language
2. Select and apply a pattern to improve the API

Step 0: Understand the Sample API Requirements

Baseline: Let’s assume that the following customer search API has been implemented and released:

API description MAPTutorial0Sample

data type Customer {"name": D<string>, "address": D<string>, "bday": D<string>}

endpoint type CustomerLookup 
exposes 
  operation findCustomer 
    expecting payload "searchFilter": D<string> 
    delivering payload "customerList": Customer*

The search filter is a simple string value D<string>. The response message of the findCustomer operation in the API description can return many results Customer*; each of these results describes all data that has been collected about a particular customer. Hence, preparing the response data on the API provider side (and processing it on the client side) takes rather long.

Goal: Our task is to improve the above API description to support an incremental query processing. In other words, the search results should be returned in multiple manageable chunks (or slices).

Step 1: Explore Website and Pattern Language

Designing Web APIs is a complex undertaking. Hence, the API Patterns website and language might be a bit overwhelming at first glance.¹ To be able to select a pattern that helps us meet the goal established in Step 0, we first have to get an overview and orient ourselves. There are several ways to do that.

Task 1.1: Home page and cheat sheet

Have a look at the home page of the MAP website:

1. Which API design questions are raised?
2. Which microservice pattern categories are available (hint: there are five)?

Solution (click to show)

Next, browse the the cheat sheet presenting some API design heuristics:

1. Which API design topics does the cheat sheet cover?
2. Does any of the issues-to-patterns tables mention “performance problems” (that occur according to our baseline from Step 0)?

Solution (click to show)

Task 1.2: Pattern categories and filters

Have a look at the pattern categories page:

• Do any of these categories cover the content of request and response messages (remember: we are supposed to redesign at least one such message)?
• How about API quality tradeoffs?

Solution (click to show)

Optional tasks

Also try out the following website and language navigation options:

1. Go to Pattern Filters. Which scopes and phases are defined? Which phase classification is used?
2. Move on to Patterns by Quality. Is performance featured? Which patterns can help improve it?
3. Finally, quickly also review the alphabetical Pattern Index. Are there any additional patterns worth exploring at this point?

Solution(s) (click to show)

Step 2: Select and Apply a Pattern to Improve the API

Task 2.1: Review Pagination Pattern

Now read the problem statement and the solution summary and sketch of the Pagination pattern (note that our API patterns book has a much more detailed solution description including variants). Optionally, also read its context, forces, and consequences sections (note: you can use the links to the section at the top of the pattern page to navigate within the pattern):

1. Does the pattern address/solve the problem stated in the baseline (Step 0)?
2. Which variants exist (hint: consult Chapter 7 of our book or the EuroPLoP 2017 paper version of the pattern?

Solution(s) (click to show)

Task 2.2: Apply Pagination to sample contract

Improve the API contract to apply one of the Pagination variants as described under “How it Works” on the patterns page.

Solution (click to show)

API description MAPTutorial0Sample

data type Customer {
  "name": D<string>, 
  "address": D<string>, 
  "birthday": D<string>}
data type CustomerPage {
  "pageContent": Customer*,
  "navigation": PageCursor, 
  "statistics": PageMetadata?}
data type PageCursor {
  "thisPage": PageID, 
  "previousPage": PageID, 
  "nextPage": PageID}
data type PageMetadata {
  "totalResultCount": MD<int>, 
  "pageSize": MD<int>, 
  "offsetNumber": PageID}
data type PageID L<string>

endpoint type CustomerLookup 
exposes 
  operation findCustomer with responsibility RETRIEVAL_OPERATION
    expecting payload "searchFilter": D<string> 
    delivering payload "customerList": Customer*

  operation findCustomerPaginated with responsibility RETRIEVAL_OPERATION
    expecting payload "searchFilter": D<string> // could specify page size here  
    delivering payload "customerPage": CustomerPage    

End Result

Having completed the above step(s), you should have gained an overview of MAP language and Website, familiarized yourself with structure and content of the Pagination pattern and created a single artifact:

• Enhanced API description (service contract).

Note: A more complete example of pagination can be found in the Lakeside Mutual (LM) sample implementation that is available in a public GitHub repository.

Next: Self-Paced Exercise and Repetition Questions

You can find a self-paced tutorial and repetition questions with the same basic scope here. And an introductory article can be found here.

Feedback appreciated! Contact us.