Best Practices for RESTful API Design using RAML

This is an example API design using RAML. The implementation of this API using Mulesoft Studio is coming soon. In its current state, the project demonstrates the following:

• Best practices for RESTful API design.
• Use of built in aspects of the HTTP protocol (status codes, headers, etc.).
• Use of various RAML features.
• Performance considerations when designing the API for mobile applicationsl; that is feficient use of the network.
• Important Note: In its current state, this projects includes the API design using RAML.
• Coming Soon: I am working on implementing this RESTful API in Mulesoft with test stubs for the consumer and provider systems. The implementation will be added to this project soon.

This API, in its present state, contains a single resource /customers. The operations allowed on the /customers resource are listed below. For more details see API Documentation.

• List Customers
  • HTTP GET
  • The request must contain If-Modified-Since header to specify the datetime. The records updated since this datetime will be returned.
  • In addition to the request header If-Modified-Since to obtain only a subset of customers, this operation supports pagination. For more details see Use Case 1: Maintain a Copy of Customers Data.
• Create a New Customer
  • HTTP POST
• Update a Customer
  • Supports both HTTP PATCH and HTTP PUT.
  • HTTP PATCH is supported to support the performance optimization needed for mobile applications. For more details see Use Case 2: API Usage Optimization for Mobile Applications
• Remove a Customer
  • HTTP DELETE

You can use this project in various ways:

• Use the api.raml (and the subdirectories/files) in your API design. This project makes use of RAML features making it easy to extend it to support future resources such as products and orders. For more details see Use Case 3: Extention of this API to Support Future Resources.
• Create your own Mulefost project by importing api.raml using APIkit.
• Create an API in API Designer (a part of Mulesoft Anypoint Platform) and import it into your Mulesoft project using APIkit.

A detailed API definition is provided at:

• API Documentation

Detailed commentaries on various use cases of this API are provided at:

• Use Case 1: Maintain a Copy of Customers Data
• Use Case 2: API Usage Optimization for Mobile Applications
• Use Case 3: Extending the API to Support Future Resources