Wednesday, September 26, 2018

Introduction to RESTful API Modeling Language (RAML)



Introduction to RESTful API Modeling Language (RAML)

1. Overview

RAML is a YAML based language which is built on YAML1.2 and JSON for describing RESTful APIs. It provides all the information necessary to describe Restful API.
It focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, Restful constraints.

2. Requirement

Before jumping to RAML. Let’s assume we have to create one web application which is exposing CRUD Operations and couple of query parameters to access USER resources:
· POST /api/v1/users
· GET /api/v1/users
· GET /api/v1/users?username={username}
· GET /api/v1/users/{userId}
· PUT /api/v1/users/userId{}
· DELETE /api/v1/users/{userId}
All the API’s are secured via Basic Authentication and all the communication will be done over HTTPS and all the request response will be in JSON format.

3. Implementation


3.1 Adding Root level details

To start with RAML, first create a file with extension .raml and at rool level, you need to define the setting starting with RAML version.
1. #%RAML 1.0
2. title: REST Services API using Data Types
3. version: v1
4. protocols: [ HTTPS ]
5. baseUri: http://hostname/api/{version}
6. mediaType: application/json

#1 defines the RAML version
#2 Title of the application
#3 API versions
#4 HTTP or HTTPS channel
#5 URL of the application where ‘versions’ refers to a property which will be replaced with #3 version.
#6 Media type for the request/response.

3.2 Add Security

Security should also be added at the root level and as I mentioned earlier all the API’s are secured via Basic Authentication.

  1. securitySchemes:
  2. basicAuth:
  3. description: Basic Authnetication to authenticate API
  4. type: Basic Authentication
  5. describedBy:
  6. headers:
  7. Authorization:
  8. description: Used to send the Base64-encoded "username:password" credentials
  9. type: string
  10. example: Authorization NTA5NjUsInN1YiI6IkJhcmNsYXlzX1BheW1lbnRfU2Vydmlj
  11. responses:
  12. 401:
  13. description: |
  14. Unauthorized. Username/password is invalid


3.3 Add Data type

Once you are done with security then starts adding all your data type. In my case I will define it for users.
There are multiples ways to define your type:
1. You can create a new file users .raml and include the path over here (Will discuss at the end of this document).
2. Define the types after root setting using expanded syntax
3. Or you can do it via shortcut.

  1. types:
  2. Users:
  3. type: object
  4. properties:
  5. id:
  6. required: true
  7. type: integer
  8. username:
  9. required: true
  10. type: string
  11. roles:
  12. required: false
  13. type: string

Now we will see how we can define the user using shorthand.
1. types:
2. Users:
3. properties:
4. id: integer
5. username: string
6. roles?: string

? -> Adding to any property declares that the field is not mandatory.

3.4 Define Resource, method, URL parameters and query parameters


To define a resources
/users:
To add the method
/users:
get:
post:

To add the URL parameters
/users:
get:
post:
/{userId}:
get:
put:
delete:

To add the Query Parameters:
/users:
get:
description: List all users with/without filters
queryParameters:
name?: string
roles?: string
post:
/{userId}:
get:
put:
delete:

Over here, we have seen how we can declare the resources with VERB and how we can define path as well as query parameters.

3.5 Request and Response Body

In above example we have defined the users resources with POST method but have not defined the payload. Let’s see how we can add payload, response and Status Code to an API.
/users:
get:
description: List all users with/without filters
queryParameters:
name?: string
roles?: string
post:
description: create a new user
body:
application/json:
type: Users
example: { "id" : 101, "name" : "Abdul Waheed”, “roles”:”Admin” }
responses:
201:
body:
application/json:
type: Users
example: { "id" : 101, "name" : "Abdul Waheed”, “roles”:”Admin” }
500:
   body:
     application/json:
        type: Error
       example: { "message" : "Internal Server Error, "code" : 500 }

/{userId}:
get:
put:
delete:


In this example, We are performing POST operation where we are passing Users object in the form of JSON and in response we are getting STATUS code as 201 and again response type in the form of JSON.


4. Usage of Includes in RAML
In the above example, we just took one resouces but let’s assume you have to create RAML for your application where you have many resouces and each resouces have multiple consuming API.
Handling such requirement makes our .raml file more verbose and repetetive.
Using !include, we can externalize our duplicate lengthy code.
Eg: we can put the data type for a Users object in the file types/Users.raml and the type for an Error object in types/Error.raml. Then our types section would look like this:
types:
Users: !include types/Users.raml
 Error: !include types/Error.raml


5. Completing the API
After externalizing all of the data types and examples to their files, we can refactor our API using the include facility
  1. #%RAML 1.0
  2. title: REST Services API using Data Types
  3. version: v1
  4. protocols: [ HTTPS ]
  5. baseUri: http://hostname/api/{version}
  6. mediaType: application/json
  7. securitySchemes:
  8. basicAuth:
  9. description: Basic Authnetication to authenticate API
  10. type: Basic Authentication
  11. describedBy:
  12. headers:
  13. Authorization:
  14. description: Used to send the Base64-encoded "username:password" credentials
  15. type: string
  16. example: Authorization NTA5NjUsInN1YiI6IkJhcmNsYXlzX1BheW1lbnRfU2Vydmlj
  17. responses:
  18. 401:
  19. description: |
  20. Unauthorized. Username/password is invalid
  21. types:
  22. Users:
  23. type: object
  24. properties:
  25. id:
  26. required: true
  27. type: integer
  28. username:
  29. required: true
  30. type: string
  31. roles:
  32. required: false
    type: string
  33. /users:
  34. get:
  35. description: List all users with/without filters
  36. queryParameters:
  37. name?: string
  38. roles?: string
  39. response:
  40. 200:
  41. body:
  42. application:json
  43. type: Users[]
  44. example: [
  45. {“id”:1,”username”:”Abdul”}
  46. {“id”:2, “username”:”Waheed”}]
  47. post:
  48. description: create a new user
  49. body:
  50. application/json:
  51. type: Users
  52. example: { "id" : 101, "name" : "Abdul Waheed”, “roles”:”Admin” }
  53. responses:
  54. 201:
  55. body:
  56. application/json:
  57. type: Users
  58. example: { "id" : 101, "name" : "Abdul Waheed”, “roles”:”Admin” }
  59. 500:
  60.    body:
  61.      application/json:
  62.         type: Error
  63.        example: { "message" : "Internal Server Error, "code" : 500 }
  64. /{userId}:
  65. get:
  66. put:
  67. delete:

In my next blog, I ll talk about different RAML tools and the difference between SWAGGER (recently renamed to OAS) Vs RAML and which one to prefer.

Friday, June 1, 2018

Private method in Java 9



As we know till Java 7, we are not allowed to add any concrete function to the Interface, All the function should be abstract and must be implemented in Child class which is implementing the interface. i.e. an interface can only have
  • Constant variable
  • abstract method

With Java 8, we can add static and default method as well in an Interface. Check my blog on Java 8 for more details. So, an Interface now can have
  • Constant Variable
  • Abstract Method
  • Default Method
  • Static Method

and with Java 9, It become more powerful and now we can add private method and private static method.




but why do we need private function in an Interface. Let’s understand this with an example.




In above example, we can observe that all the default function has same code to create database connection (duplicate code) and fetching the data and database details is also exposed to outside the world.


So over here, Private method will come to rescue. Check below example where the database code reside in one private method which can be easily accessible to all default function in that interface and it is also hidden to the outside world.

These private methods will improve code re-usability inside interfaces and will provide choice to expose only our intended methods implementations to users. These methods are only accessible within that interface only and cannot be accessed or inherited from an interface to another interface or class.

Rules For using Private Methods in Interfaces

  • Private interface method can be static or instance and In both cases, the private method is not inherited by sub-interfaces or implementations.
  • Private interface method cannot be abstract. it will give compiler error.
  • Private method can be used only inside interface and other static and non-static interface methods.
  • Private non-static methods cannot be used inside private static methods.
  • We should use private modifier to define these methods and no lesser accessibility than private modifier.
Java 9 code can be downloaded from GITHUB

How TOPT Works: Generating OTPs Without Internet Connection

Introduction Have you ever wondered how authentication apps like RSA Authenticator generate One-Time Passwords (OTPs) without requiring an i...