DEVSECOPS: Swagger

 

Reference: https://www.javatpoint.com/swagger

Swagger is the standard way of documenting the Standard APIs. 

Swagger is one of the popular tools used for generating an interactive documentation. It generates an interactive API for the users so that they can understand about the API more quickly.

For the other developers to be able to use our API, the API must be properly documented; otherwise, how would they know that what are the endpoints exposed by the api and what are the operations supported on those endpoints? What parameters should they pass, and what will they get back? What authentication methods to use?. To answer these questions, it is very important to document the APIs; if you want APIs to be consumed and properly used.

Swagger and Open API specification are the ways to document an API specifying that what exactly APIs can do

There are several types of APIs, but the swagger specifically deals with the Web API.

JSON file is passed over the web, it is unlike YAML thus YAML is for configuration files that are not passed over the web.

Documentation in Swagger: What is Autogenerated documentation?

Tools such as Swagger takes the OAS files and generate the HTML documentation from it so that it can be updated on the web. As long as the OAS file is kept up to date then the documentation is likely to be more accurate rather than writing the documentation manually. It also allows you try out the requests from within the documentation so that it can help the developer for implementing the code.

Anatomy of a Request

There are five different parts to be found in the Http request:

1. Method: The method describes the action to be performed. The methods could be POST, PUT, DELETE, GET.
2. URL: It specifies the name on which the action is to be performed.
3. Query parameters
4. Headers: Headers are used to store the information about the request.
5. Body: Body contains the additional data.

URL is broken down into several pieces:

Scheme, Host, Base Path, Path

Security

Here, Security means authentication and authorization. Authentication means to validate the user through their username and password. The authorization means allowing the user to access the data.

The security can be set in the following ways:

• None: Here, None means that no security is set to access the API.
• Basic Auth: It means that the username and password are set for each request.
• API Key: The key is set to access the API.
• OATH: It is an authorization scheme.

AWS IBM Capstone Part 2 - Lambda, API Gateway portion

Step 1: Create a NodeJs Lambda function

• Select Lambda service
• Click on Create function button
• Select Author From Scratch.
• Function name : ApiFunc
• Runtime: Node.js 14.x (arm68)
• Permission ---> change default execution role
• Select create new role from AWS policy Template
• Provide the role name apifuncrole
• Click on Create function button (this will take some time)

Step 2: Use the below code for the Lambda function 

'use strict';

const https = require('https');

exports.handler = async (event) => {

    let dataString = '';

    const response = await new Promise((resolve, reject) => {

        const req = https.get("https://jsonplaceholder.typicode.com/todos/1", function(res) {

          res.on('data', chunk => {

            dataString += chunk;

          });

          res.on('end', () => {

            resolve({

                statusCode: 200,

                body: JSON.stringify(

                        {

                            "data": JSON.parse(dataString).title,

                            "timestamp": new Date()

                        }, null, 4

                    )

            });

          });

        });

       

        req.on('error', (e) => {

          reject({

              statusCode: 500,

              body: 'Something went wrong!'

          });

        });

    });

   

    return response;

};

Then Click on  File--->save and Click on Deploy

Step 3: Create Rest API using API Gateway.

• Select API Gateway Service
• Click on Create API button
• Select RestAPI
• Click on Build button
• Select New API
• Put in any Api Name: myapi
• Click on Create Api Button.

Step 4: Create a Resource

• Select Action--> Create Resource
• Resource Name: what-is-my-title
• Click on Create Resource Button

Step 5: Initialize GET Method for Resource

• Select resource what-is-my-title
• Go to Action
• Create Method from Drop down 
• select Get Method
• click on tick mark

Step 6:Choose the integration point for your new method (link to your lambda function).

• Click on Get Method 
• Integration Type: Lambda Function
• Select check box Use Lambda proxy Integration
• Lambda function: <<Lamda function you created in step 1>> 
• Click on Save button

Step 7: Staging the API (masking it with the first layer or exposing the service) www.google.com/irfan-api

• Select GET and Goto Action--->Deploy API
• Deployment Stage : New Stage
• Stage Name: api
• Click on the Deploy button.

Step 8: You will find a prompt indicating: Invoke URL on the top and open that URL in a new tab and at the end of the URL.

• add what-is-my-title
• You will be able to see the title and current date and time

Step 9: Download the Json file for API Gateway.

• In the Stages page, click on Export tab 
• select the Swagger
• select Export as Swagger and click on json. 

Step 10: Go to IAM services, click on Roles Tab, take screen shot and copy IAM Role policy 

DEVSECOPS: RESTful API (HTTP Methods/Verbs)

 

Reference: https://www.youtube.com/watch?v=Rcw0s_qLfW0

you can use POSTman to tryout REST API.

Common features / groups of HTTP methods are:

• SAFE
• IDEMPOTENT
• CACHEABLE

SAFE Methods

The method is safe if:

• the request does not alter the state of the server such as READ only operation. the client just ask for information and does not require any change 
• the request should not introduce any side effect or load on server and it should not trigger any external call.
• GET and HEAD method are considered safe methods.

IDEMPOTENT Methods

it means no matter how many time you execute on that resource, you will get generate the same thing (example in mathematical sense, adding 0 or times by 1)

• using of this method will keep the server in the same state, only that logs or other statistics will be affected.
• PUT and DELETE method are considered idempotent Methods
• ALL SAFE (GET and HEAD method) methods are considered idempotent Methods, but all idempotent are not safe.

CACHEABLE Methods

response of request can be cacheable (it can be stored and used later).

• not all methods are cacheable.
• GET and HEAD are cacheable 

GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, CONNECT, TRACE

GET Method:

should be concise and efficient due to load and rapid change of internet example:

GET request retrieves data but we can attach header properties to get more precise data:

• If-Modified-Since
• If-Match
• If-Range
• eTag and If-None-Match (to see if it is still same or modified) see below:

This will just check without generating the response body (which will save time).

POST Method:

submit an entity that will cause a change in resource state or it can affect the server.

• POST is a request to server for accepting entity in request body as resource or sub-resource.
• use cases: signup and post blog.
• the response statusCode for POST will always be either 201 (CREATED) or 200 (OK).
• response are not cacheable but can be cacheable if configured with Cache-Control or Expires header-field or redirect.

PUT Method:

if exists, replace resource, if not, create resource with the request body (PUT identifies first!!)

• use cases: update user info
• the response statusCode for PUT will be 201 (CREATED) if it creates.
• difference between PUT and POST:

DELETE Method:

request to server to delete a resource identified by the URI

• delete method statusCode:
• 200 (OK) - delete successful, response body existed
• 202 (ACCEPTED) - delete request accepted but not yet executed
• 204 (NO CONTENT FOUND) - delete request is successful but no content in response body

HEAD Method:

request only the header (the metadata (the size, and other properties)). 

• It is similar to GET but not the same.
• use cases: performance, if we want to download a file, but if the file is big, we will not download it.
• Content-Length: 12324(value in bytes)
• statusCode 200 (OK)

OPTIONS Method:

a method to request comms options for the resource identified by the URI.

• normally, request from options method does not contain a response body, but it can be added to make it more informative (look at server compabilities first!)

PATCH Method:

a method to partially modify an existing resource.

• it is similar to PUT method
• difference between PATCH and PUT as below:

Guideline for Usage: