In this article, you will learn what an API specification is and how to Design a RESTful API specification using AnyPoint Platform > Design Center – Mulesoft RAML Example.
What is API Specification ?
An API Specification is a blueprint for APIs which provides a detailed understanding of how an API behaves, what kind of request an API is accepting, what kind of response it is giving, and what are the mandatory fields/datatype, etc…
Steps for Designing RESTful API Specification in Mulesoft RAML Example :
Step 2: Now, In the Design Center Click on Create New > New API Spec as shown in the below screenshot
Step 3: After Clicking New API Spec then it will appear like the below screenshot
Now, Please Enter your API Specification Name. Actually, Design Center will allow us to write RAML in 2 modes, the First mode is Writing From Scratch with Interactive documentation support, Also we feel a little bit of coding experience in this mode, and the Second One is through a visual interface guide.
Now we can move forward with the first mode.
After choosing, click on Create API Spec
Step 4: Now, We are going to write our first API specification as shown in the below
#%RAML 1.0 title: MyFirstSpecification version: v1 description: An API Having One Resource which will fetch all the user details. types: User: description: Single User Data type: object properties: email: string name: string phone: string UserList: description: List of customers type: UserList /users: get: description: Get the list of all users responses: 201: body: application/json: type: UserList
Each RAML file must start with #%RAML, the title consists of the name of the RAML file. Here, version: v1 means the version of the API that we are developing( It is not the RAML Version).
From line no. 5 to 15: It is defining some types, First one is User which is a type of object having some properties like email, name, phone… and this User type will return only single-user data and the Second one is UserList which is a type of user-array and this will return an array of users data.
From line no. 17 to 24: /users is the unique name given for identifying a resource, get is an example for request method like post/put/delete… And this resource is giving response with a status code like 201 and a list of users in the JSON format.
That’s it, Now we need to publish it to API exchange So that it is available to everyone in your organization.
Now, Enter Asset Version and then Click On Publish to Exchange
Finally, We Successfully Created and published our first API Specification to API Exchange.