MuleSoft from Start: A Beginner’s Guide — Session 3: Design an API Specification

In the last session, we learned the basics of an API and API-Led Connectivity.

• Analogies and Examples
• HTTP Methods
• URI
• Query Parameters
• HTTP Status Codes
• API-Led Connectivity

In this week’s session, we started designing our own API Specification for a blog API. Let’s see a summary of what we did!

Note: The links and some notes from the session have been added to the GitHub repository for you to follow through with what I’m doing in the video. You can find both recordings (the complete and the shorter one) at the end of the post.

Requirements

Before jumping right into Anypoint Platform, we first created our requirements on a text file to have a clearer image of what we’re trying to make. We created some resources and data types.

We defined resources as “the nouns of our APIs — stuff we can use a CRUD operation on.”

CRUD

• Create
• Read
• Update
• Delete

Resources

• Articles
• Writers
• Categories
• Comments

Data Types

- article
    - id
    - slug
    - title
    - content
    - writerId
    - categoryId
    - comments
- writer
    - id
    - name
    - bio
    - articles
- category
    - id
    - name
    - articles
- comment
    - id
    - content
    - author
    - articleId
- error
    - code
    - description

After creating our notes, we were now able to start creating our API Specification in Design Center.

Design Center

In your Anypoint Platform account (you can use a free trial), go to Design Center and create a new API Specification. Make sure to select the Guide me through it option. Especially if you’re not familiar with RAML or OAS.

In the API Summary window, select the following values:

• Title = Blog API
• Version = 1.0.0
• Protocols = HTTP, HTTPS
• Media type = application/json
• Base URI = /
• Description = # Welcome to Maxine’s Blog!

Data Types

In the Data Types section from the left side of the screen, click on the + button to start creating more items. Create the following data types with the properties listed below.

Comment (Object)

• id — Required — Number
• content — Required — String
• author — Required — String
• articleId — Required — Number

Example:

{
 "id": 1,
 "content": "Hey, this was a nice post!",
 "author": "Alex Martinez",
 "articleId": 1
}

Article (Object)

• id — Required — Number
• title — Required — String
• content — Required — String
• writerId — Required — Number
• categoryId — Number
• comments — Array of Comment
• slug — Required — String

Example:

{
 "id": 1,
 "title": "The Importance of Regular Exercise",
 "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac est eu mauris faucibus consectetur. Nunc vehicula hendrerit nulla, non vulputate justo ultrices sit amet. Mauris varius lorem sit amet sem laoreet, id lacinia eros auctor. Donec tincidunt augue vel dolor pharetra tincidunt. Aliquam dapibus sed neque vitae sagittis. Sed sit amet nibh id nunc vehicula laoreet. Morbi fermentum auctor est, eu tempor tortor lobortis nec. Etiam tincidunt, lorem a viverra facilisis, nunc lorem aliquet magna, euismod ullamcorper ligula metus et augue.",
 "writerId": 1,
 "categoryId": 1,
 "comments": [
  {
   "id": 1,
   "content": "Hey, this was a nice post!",
   "author": "Alex Martinez",
   "articleId": 1
  }
 ],
 "slug": "importance-of-regular-exercise"
}

Category (Object)

• id — Required — Number
• name — Required — String
• articles — Array of Article

Example:

{
 "id": 1,
 "name": "Mental Health",
 "articles": [
  {
   "id": 1,
   "title": "The Importance of Regular Exercise",
   "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac est eu mauris faucibus consectetur. Nunc vehicula hendrerit nulla, non vulputate justo ultrices sit amet. Mauris varius lorem sit amet sem laoreet, id lacinia eros auctor. Donec tincidunt augue vel dolor pharetra tincidunt. Aliquam dapibus sed neque vitae sagittis. Sed sit amet nibh id nunc vehicula laoreet. Morbi fermentum auctor est, eu tempor tortor lobortis nec. Etiam tincidunt, lorem a viverra facilisis, nunc lorem aliquet magna, euismod ullamcorper ligula metus et augue.",
   "writerId": 1,
   "categoryId": 1,
   "comments": [
    {
     "id": 1,
     "content": "Hey, this was a nice post!",
     "author": "Alex Martinez",
     "articleId": 1
    }
   ],
   "slug": "importance-of-regular-exercise"
  }
 ]
}

Writer (Object)

• id — Required — Number
• name — Required — String
• bio — Required — String
• articles — Array of Article

Example:

{
 "id": 1,
 "name": "Esmeralda",
 "bio": "20+ years of experience in IT and very smart.",
 "articles": [
  {
   "id": 1,
   "title": "The Importance of Regular Exercise",
   "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac est eu mauris faucibus consectetur. Nunc vehicula hendrerit nulla, non vulputate justo ultrices sit amet. Mauris varius lorem sit amet sem laoreet, id lacinia eros auctor. Donec tincidunt augue vel dolor pharetra tincidunt. Aliquam dapibus sed neque vitae sagittis. Sed sit amet nibh id nunc vehicula laoreet. Morbi fermentum auctor est, eu tempor tortor lobortis nec. Etiam tincidunt, lorem a viverra facilisis, nunc lorem aliquet magna, euismod ullamcorper ligula metus et augue.",
   "writerId": 1,
   "categoryId": 1,
   "comments": [
    {
     "id": 1,
     "content": "Hey, this was a nice post!",
     "author": "Alex Martinez",
     "articleId": 1
    }
   ],
   "slug": "importance-of-regular-exercise"
  }
 ]
}

Error (Object)

• code — Required — Number
• description — Required — String

Example:

{
 "code": 500,
 "description": "There was an internal error. Nothing on your side tho!"
}

Resources

After creating the data types, we started creating the resources. Unfortunately, we were only able to finish the Articles resource. Your homework is to create the Writers, Categories, and Comments resources.

/articles

- GET (to retrieve the list of articles)
  - Responses:
    - 200 - OK
      - Body:
        - Media type: application/json
        - Type: Array of Article
    - 404 - Not Found
      - Body:
        - Media type: application/json
        - Type: Error
    - 500 - Internal Server Error
      - Body:
        - Media type: application/json
        - Type: Error

- POST (to create a new article)
  - Responses:
    - 201 - Created
      - Body:
        - Media type: application/json
        - Type: Article
    - 400 - Bad Request
      - Body:
        - Media type: application/json
        - Type: Error
    - 409 - Conflict
      - Body:
        - Media type: application/json
        - Type: Error
    - 500 - Internal Server Error
      - Body:
        - Media type: application/json
        - Type: Error
  - Body:
    - Media type: application/json
    - Type: Object
    - Properties:
      - title - Required - String
      - content - Required - String
      - writerId - Required - Number
      - categoryId - Number
      - slug - Required - String

/articles/{slug}

• URI Parameter Name = slug
• Required = true
• Type = String

- GET (to retrieve one article)
  - Responses:
    - 200 - OK
      - Body:
        - Media type: application/json
        - Type: Article
    - 404 - Not Found
      - Body:
        - Media type: application/json
        - Type: Error
    - 500 - Internal Server Error
      - Body:
        - Media type: application/json
        - Type: Error

- PUT (to update an existing article)
  - Responses:
    - 200 - OK
      - Body:
        - Media type: application/json
        - Type: Article
    - 400 - Bad Request
      - Body:
        - Media type: application/json
        - Type: Error
    - 500 - Internal Server Error
      - Body:
        - Media type: application/json
        - Type: Error
  - Body:
    - Media type: application/json
    - Type: Article

- DELETE (to delete an existing article)
  - Responses:
    - 204 - No Content
    - 404 - Not Found
      - Body:
        - Media type: application/json
        - Type: Error
    - 500 - Internal Server Error
      - Body:
        - Media type: application/json
        - Type: Error

Homework

Before the next session, you have to finish creating the resources in our API Spec for Writers, Categories, and Comments. We just finished the Articles resource in the session.

Recordings

Finally, here are the two recordings you can find about this session.

• The complete video on Twitch
• The edited/clean/shorter version on YouTube

Here you can find the shorter version from YouTube:

And here you can find the complete video from Twitch:

Please let me know if you have any comments, suggestions, or just general feedback for me!