Friday, 29 June 2018

Part 1 - REST API Best practices and implementing them with Spring Boot

This article describes the best practices of implementing REST API.

Before we jump into the actual implementation, lets first understand the design principles involved in API design.

API Design principles

  1. Present APIs as products
    • APIs are not integration services that happen to use HTTP and JSON
    • They are business products that must be managed as a complete product offering
    • And although created and managed by different teams they should have a similar look and feel
  2. Design APIs with the consumer in mind
    • Develop APIs as though you consumers are your customers
    • APIs should be more developer-friendly and Easy to Consume
    • Simple to Expose to external third-parties in future
    • Don't leak internal context to the consumer
    • Make APIs easy to learn, hard to misuse, audience-oriented
  3. Prefer REST-based services over SOAP

REST API Design principles

  1. Use RESTful URIs and actions
    • /policies - refers to a policy resource collection
    • /policies/7895544 - refers to a policy resource collection
  2. Use HTTP verbs to act on you resources
    • Resources should be acted on using HTTP methods GET, PUT, POST, PATCH, DELETE for example GET /policies/789554
    • HTTP methods should perform predictable actions on the resource. For example, don't use POST to retrieve a resource, and don't use DELETE to create a resource.
  3. Nouns are good, verbs are bad
    • Resources must use plural nouns, such as accounts and not account
    • Do not use verbs in URI, /getaccount or createcar
    • The method exposing the webservice should be verb not the associated URI
  4. Use sub-resources to represent relationships
    • For e.g if a Department has many Employees and you need to get the list of employees in a department, the URI should be 
      GET /departments/  - Get all Departments
      POST /departments/  - Create a Department
      GET /departments/1234  - Get a Department
      GET /departments/1234/employees - Get all Employees in a Department
      POST /departments/1234/employees - Create an Employees in a Department
      GET /departments/1234/employees/2 - Get a Employee in a Department

  5. Version your API
    • All APIs should be versiones
    • Use only a major version number prefixed with a "v", eg /v1
  6. HATEOUS compliant
    • The API should be HATEOUS compliant. All future actions the client may take are discovered within resource representations returned from the server. The media types used for these representations, and the link relations they may contain, are standardized.
    • For e.g for a GET /departments/
    • {
      "id" : 1,
      "name" : "Head Office",
      "Address" : "In a far galazy",
      "links" : [
             "rel" : "self",
             "href" : "http//"
             "rel" : "find",
             "href" : "http//{id}",
             "type" : "GET"
             "rel" : "delete",
             "href" : "http//{id}",
             "type" : "DELETE"
    • As seen above the response has a link to self and also other possible resources the client can use

  7. API must be secured
    • APIs must be secured and there are no exceptions
    • OAuth2.0 can be used for securing APIs.
    • Choose the best grant type e.g authorization code/password/client credential
  8. Error Handling
    1. Use descriptive error messages and status code
    2. For e.g if the request is to find a employee and the employee id provided is not correct, return a 404 Resource Not Found status code and not a 200 OK
    3. Trap all errors and always return a valid JSON response

    4. {
          "timestamp": "2018-06-27T12:42:39.238+0000",
          "status": 400,
          "error": "Bad Request",
          "message": "Do not send ‘id’ as part of request",
          "path": "/spring-security-oauth-resource/rest/v1/employees"

      Another example for multiple errors would be like below:
          "status": 405,
          "timestamp": "02-07-2018 03:16:55",
          "path": "/spring-security-oauth-resource/rest/v1/departments",
          "message": "Validation failed for object='department'. Error count: 3",
          "sub_errors": [
                  "field": "name",
                  "message": "name cannot be Blank"
                  "field": "id",
                  "rejectedValue": 1111,
                  "message": "must be null"
                  "field": "knownName",
                  "message": "known_name cannot be Blank"
  9. Things to avoid
    • Dont use querystring argumets to retrieve by primary key:
    • For eg : dont use /policies/?policy_number=32323
      Rather Use /policies/12333
    • Dont use mixed-case in URLs:
    • For eg : dont use /Policies/32323
      Rather Use /policies/12333

Thursday, 11 January 2018

Friday, 22 December 2017

Java Blockchain Mining and Consensuses

Mining and Consensuses in Blockchain

In the previous blog we got to know what a Blockchain is, and how you can we create a Java based Blockchain which can not be tampered (Integrity).

Blockchain has couple of more design principles other than Integrity : Decentralized, Consensuses, Public Ledger etc. Before we jump to Mining it is important to understand these concepts first.

Public Ledger 

Assume that different participants are adding transactions and blocks to a Blockchain. That means there has to be a central Blockchain that is accessible to all, since all participants needs to add block to the existing Blockchain, This means there has to be a master participants governing and storing the Blockchain. But this is against the principle of Blockchain (Decentralized). There is no master participant in the network. To solve the above issue, each participant keeps a copy of the Blockchain with itself. Once a block is added, it is distributed across the network and all participants update their Blockchain. This concept is called Public Ledger. A ledger (list of transactions) which is public.

But this causes another problem in the network.

Lets assume that 2 participants are trying to add a block, simultaneously to a Blockchain.  Only one can be allowed to do so and the other has to be discarded since the previous hash in that block will be invalid.

Java Blockchain tutorial

This blog provides a working Blockchain example in Java.

Before we jump into the actual code, lets first understand the basics of Blockchain.

Introduction :

Lately, you might have herd a lot of buzz around different crypto-currencies emerging in market : Bitcoin, Etherium, Ripple, Dash ... and the list goes on. The market share of Bitcoin has gone exponentially up from $ 4000 to $ 17000 in just three months. Other currencies are also following the same trend.

The reason that these currencies are getting so much traction is the common architecture design they share : Blockchain

Bitcoin is not Blockchain and Blockchain is not Bitcoin. Bitcoin is just one implementation of crypto-currency use case that can be build on Blockchain.

Share the post