41,99 €
Mehr erfahren.
- Herausgeber: Packt Publishing
- Kategorie: Wissenschaft und neue Technologien
- Sprache: Englisch
Explore the necessary concepts of REST API development by building few real world services from scratch.
About This Book
- Follow best practices and explore techniques such as clustering and caching to achieve a reactive, scalable web service
- Leverage the Gin Framework to quickly implement RESTful endpoints
- Learn to implement a client library for a RESTful web service using Go
Who This Book Is For
This book is intended for those who want to learn to build RESTful web services with a framework like Gin. To make best use of the code samples included in the book, you should have a basic knowledge of Go programming.
What You Will Learn
- Create HTTP handler and introspect the Gorilla Mux router
- OAuth 2 implementation with Go
- Build RESTFul API with Gin Framework
- Create REST API with MongoDB and Go
- Build a working client library and unit test for REST API
- Debug, test, and profile RESTful APIs with each of the frameworks
- Optimize and scale REST API using microservices
In Detail
REST is an architectural style that tackles the challenges of building scalable web services and in today's connected world, APIs have taken a central role on the web. APIs provide the fabric through which systems interact, and REST has become synonymous with APIs. The depth, breadth, and ease of use of Go, makes it a breeze for developers to work with it to build robust Web APIs. This book takes you through the design of RESTful web services and leverages a framework like Gin to implement these services.
The book starts with a brief introduction to REST API development and how it transformed the modern web. You will learn how to handle routing and authentication of web services along with working with middleware for internal service. The book explains how to use Go frameworks to build RESTful web services and work with MongoDB to create REST API. You will learn how to integrate Postgres SQL and JSON with a Go web service and build a client library in Go for consuming REST API. You will learn how to scale APIs using the microservice architecture and deploy the REST APIs using Nginx as a proxy server. Finally you will learn how to metricize a REST API using an API Gateway.
By the end of the book you will be proficient in building RESTful APIs in Go.
Style and Approach
This book is a step-by-step, hands-on guide to designing and building RESTful web services.
Sie lesen das E-Book in den Legimi-Apps auf:
Seitenzahl: 330
Veröffentlichungsjahr: 2017
Ähnliche
BIRMINGHAM - MUMBAI
Building RESTful Web Services with Go
Copyright © 2017 Packt Publishing
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First published: December 2017
Production reference: 1261217
ISBN 978-1-78829-428-7
www.packtpub.com
Credits
Author
Naren Yellavula
Copy Editors
Dhanya Baburaj
Safis Editing
Reviewer
Anshul Joshi
Project Coordinator
Sheejal Shah
Commissioning Editor
Aaron Lazar
Proofreader
Safis Editing
Acquisition Editor
Denim Pinto
Indexer
Rekha Nair
ContentDevelopmentEditor
Sreeja Nair
Graphics
Jason Monteiro
Technical Editor
Rutuja Vaze
Production Coordinator
Nilesh Mohite
About the Author
Naren Yellavula—fondly called by the developer community as Naren Arya—started his programming career in the funniest way. He ditched mechanical engineering for computer science after watching The Matrix for the first time. With dreams of coding a mini world, he continuously sharpened his practical skills. Initially, he built few a mobile applications. Then, he completely moved into the space of full stack development. He always believed that computers and software can help make this world a better place. He wrote 120+ development articles on various open source technologies, including Go and Python. He is also one of the few young speakers at the PyCon India conference (he spoke at Bangalore in 2015 and Delhi in 2017). With detailed knowledge of web scraping and REST APIs, he dived into multiple domains such as cloud telephony and cloud-based web services. On this journey, he bathed in a lot of design decisions. He currently works as a software engineer for Citrix R&D, India. Naren is a great fan of Go personally because of the speed and intuitiveness of the language. In his spare time, he tries to educate the youth in programming and software development. He loves reading nonfiction most of the time, and Victorian and Russian fiction sometimes.
Acknowledgments
About the Reviewer
Anshul Joshi is a data scientist with experience in recommendation systems, predictive modeling, neural networks, and high-performance computing. His research interests encompass deep learning, artificial intelligence, and computational physics. Most of the time, he can be found exploring GitHub or trying anything new he can get his hands on. His blog can be found at https://anshuljoshi.com/.
www.PacktPub.com
For support files and downloads related to your book, please visit www.PacktPub.com.
Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at [email protected] for more details.
At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.
https://www.packtpub.com/mapt
Get the most in-demand software skills with Mapt. Mapt gives you full access to all Packt books and video courses, as well as industry-leading tools to help you plan your personal development and advance your career.
Why subscribe?
Fully searchable across every book published by Packt
Copy and paste, print, and bookmark content
On demand and accessible via a web browser
Customer Feedback
Thanks for purchasing this Packt book. At Packt, quality is at the heart of our editorial process. To help us improve, please leave us an honest review on this book's Amazon page at https://www.amazon.com/dp/1788294289.
If you'd like to join our team of regular reviewers, you can email us at [email protected]. We award our regular reviewers with free eBooks and videos in exchange for their valuable feedback. Help us be relentless in improving our products!
Table of Contents
Preface
What this book covers
What you need for this book
Who this book is for
Conventions
Reader feedback
Customer support
Downloading the example code
Downloading the color images of this book
Errata
Piracy
Questions
Getting Started with REST API Development
Types of web services
REST API
Characteristics of REST services
REST verbs and status codes
GET
POST, PUT, and PATCH
DELETE and OPTIONS
Cross-Origin Resource Sharing (CORS)
Types of status codes
2xx family (successful)
3xx family (redirection)
4xx family (client error)
5xx family (server error)
Rise of REST API with Single Page Applications
Old and new ways of data flow in SPA
Why Go for REST API development?
Setting up the project and running the development server
Demystifying GOPATH
Building our first service – finding the Roman numeral
Breaking down the code
Live reloading the application with supervisord and Gulp
Monitoring your Go web server with supervisord
Installing supervisord
Using Gulp for creating auto code compiling and server reloading
Understanding the gulpfile
Summary
Handling Routing for Our REST Services
Getting the code
Understanding Go's net/http package
Running the code
ServeMux, a basic router in Go
Running the code
Adding multiple handlers using ServeMux
Running the code
Introducing httprouter, a lightweight HTTP router
Installation
Program explanation
Building the simple static file server in minutes
Introducing Gorilla Mux, a powerful HTTP router
Installation
Fundamentals of Gorilla Mux
Reverse mapping URL
Custom paths
Path Prefix
Strict Slash
Encoded paths
Query-based matching
Host-based matching
SQL injections in URLs and ways to avoid them
Creating a basic API layout for URL shortening services
Summary
Working with Middleware and RPC
Getting the code
What is middleware?
Creating a basic middleware
Multiple middleware and chaining
Painless middleware chaining with Alice
Using Gorilla's Handlers middleware for Logging
What is RPC?
Creating an RPC server
Creating an RPC client
JSON RPC using Gorilla RPC
Summary
Simplifying RESTful Services with Popular Go Frameworks
Getting the code
go-restful, a framework for REST API creation
CRUD operations and SQLite3 basics
Building a Metro Rail API with go-restful
Design specification
Creating database models
Building RESTful APIs with the Gin framework
Building a RESTful API with Revel.go
Summary
Working with MongoDB and Go to Create REST APIs
Getting the code
Introduction to MongoDB
Installing MongoDB and using the shell
Working with the Mongo shell
Introducing mgo, a MongoDB driver for Go
RESTful API with Gorilla Mux and MongoDB
Boosting the querying performance with indexing
Designing an e-commerce data document model
Summary
Working with Protocol Buffers and GRPC
Getting the code
Introduction to protocol buffers
Protocol buffer language
Scalar values
Enumerations and repeated fields
Compiling a protocol buffer with protoc
Introduction to GRPC
Bidirectional streaming with GRPC
Summary
Working with PostgreSQL, JSON, and Go
Getting the code
Installing the PostgreSQL database
Adding users and databases in PostgreSQL
pq, a pure PostgreSQL database driver for Go
Implementing a URL shortening service using Postgres and pq
Defining the Base62 algorithm
Exploring the JSON store in PostgreSQL
GORM, a powerful ORM for Go
Implementing the e-commerce REST API
Summary
Building a REST API Client in Go and Unit Testing
Getting the code
Plan for building a REST API client
Basics for writing a command-line tool in Go
CLI – a library for building beautiful clients
Collecting command-line arguments in CLI
grequests – a REST API package for Go
API overview of grequests
Getting comfortable with the GitHub REST API
Creating a CLI tool as an API client for the GitHub REST API
Using Redis for caching the API data
Creating a unit testing tool for our URL shortening service
Summary
Scaling Our REST API Using Microservices
Getting the code
What are microservices?
Monolith versus microservices
Go Kit, a package for building microservices
Building a REST microservice with Go Kit
Adding logging to your microservice
Adding instrumentation to your microservice
Summary
Deploying Our REST services
Getting the code
Installing and configuring Nginx
What is a proxy server?
Important Nginx paths
Using server blocks
Creating a sample Go application and proxying it
Load balancing with Nginx
Rate limiting our REST API
Securing our Nginx proxy server
Monitoring our Go API server with Supervisord
Installing Supervisord
Summary
Using an API Gateway to Monitor and Metricize REST API
Getting the code
Why is an API gateway required?
Kong, an open-source API gateway
Introducing Docker
Installing a Kong database and Kong
Adding API to Kong
API logging in Kong
API authentication in Kong
API rate limiting in Kong
Kong CLI
Other API gateways
Summary
Handling Authentication for Our REST Services
Getting the code
How authentication works
Session-based authentication
Introducing Postman, a tool for testing REST API
Persisting client sessions with Redis
Introduction to JSON Web Tokens (JWT) and OAuth2
JSON web token format
Reserved claims
Private claims
Creating a JWT in Go
Reading a JWT in Go
OAuth 2 architecture and basics
Authentication versus authorization
Summary
Preface
Initially, SOAP-based web services became more popular with XML. Then, since 2012, REST picked up the pace and gulped SOAP in whole. The rise of a new generation of web languages, such as Python, JavaScript (Node.js), and Go, showed a different approach to web development compared to the traditional ones, such as ASP.NET and Spring. Since this decade, Go has become more and more popular due to its speed and intuitiveness. Less verbose code, strict type checking, and support for concurrency make Go a better choice for writing any web backend. Some of the best tools, such as Docker and Kubernetes, are written in Go. Google uses Go a lot in its daily activities. You can see a list of Go-using companies at https://github.com/golang/go/wiki/GoUsers.
For any internet company, the web development department is crucial. Data that the company accumulates needs to be served to the clients in form of an API or web service. Various clients (browser, mobile application, and server) consume API every day. REST is an architectural pattern that defines resource consumption in the form of methods.
Go is a better language to write web servers. It is the responsibility of an intermediate Go developer to know how to create RESTful services using the constructs available in the language. Once the basics are understood, the developer should learn other things, such as testing, optimizing, and deploying services. This book is an attempt to make the reader comfortable with developing web services.
Experts think that in the near future, as Python is moving into the Data Science space and competing with R, Go can emerge as the single go-to language in the web development space by competing with NodeJS. This book is not a cookbook. However, it offers many tips and tricks throughout your journey. By the end of the book, the reader will be comfortable with REST API development through a multitude of examples. They will also come to know about the latest practices, such as protocol buffers/gRPC/API Gateway, which will move their knowledge to the next level.
What this book covers
Chapter 1, Getting Started with REST API Development, discusses the fundamentals of REST architecture and verbs.
Chapter 2, Handling Routing for Our REST Services, describes how to add routing to our API.
Chapter 3, Working with Middleware and RPC, is about working with middleware handlers and basic RPC.
Chapter 4, Simplifying RESTful Services with Popular Go Frameworks, presents quick prototyping API with frameworks.
Chapter 5, Working with MongoDB and Go to Create REST API, explains how to use MongoDB as the database for our API.
Chapter 6, Working with Protocol Buffers and gRPC, shows how to use Protocol buffers and gRPC to obtain performance boost over HTTP/JSON.
Chapter 7, Working with PostgreSQL, JSON, and Go, explains the benefits of PostgreSQL and a JSON store for creating APIs.
Chapter 8, Building a REST API Client in Go and Unit Testing, presents techniques for building client software and API testing with unit tests in Go.
Chapter 9, Scaling Our REST API Using Microservices, is about breaking our API service into microservices using Go Kit.
Chapter 10, Deploying Our REST Services, shows how we can deploy services built on Nginx and monitor them using supervisord.
Chapter 11, Using an API Gateway to Monitor and Metricize REST API, explains how to make our services production grade by adding multiple APIs behind API Gateway.
Chapter 12, Handling Authentication for Our REST Services, discusses securing our API with basic authentication and JSON Web Tokens (JWT).
What you need for this book
For this book, you need a laptop/PC with Linux (Ubuntu 16.04), macOS X, or Windows installed. We will use Go 1.8+ as the version of our compiler and install many third-party packages, so a working internet connection is required. We will also use Docker in the final chapters to explain concepts of API Gateway. Docker V17.0+ is recommended. If Windows users have problems with the native Go installation for any examples, use Docker for Windows and run Ubuntu container, which gives more flexibility; refer to https://www.docker.com/docker-windows for more details.
Before diving into the book, refresh your language basics at https://tour.golang.org/welcome/1.
Even though these are the basic requirements, we will guide you through the installations wherever required.
Who this book is for
This book is for all the Go developers who are comfortable with the language and seeking to learn REST API development. Even senior engineers can enjoy this book, as it has many cutting-edge concepts, such as microservices, protocol buffers, and gRPC.
Developers who are already familiar with REST concepts and stepping into the Go world from other platforms, such as Python and Ruby, can also benefit a lot.
Conventions
In this book, you will find a number of text styles that distinguish between different kinds of information. Here are some examples of these styles and an explanation of their meaning.
Code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles are shown as follows: "Name the preceding program as basicHandler.go."
A block of code is set as follows:
{ "ID": 1, "DriverName": "Menaka", "OperatingStatus": true }
Any command-line input or output is written as follows:
go run customMux.go
New terms and important words are shown in bold. Words that you see on the screen, for example, in menus or dialog boxes, appear in the text like this: "It returns message saying Logged In successfully."
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this book-what you liked or disliked. Reader feedback is important for us as it helps us develop titles that you will really get the most out of.
To send us general feedback, simply e-mail [email protected], and mention the book's title in the subject of your message.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide at www.packtpub.com/authors .
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the example code
You can download the example code files for this book from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
You can download the code files by following these steps:
Log in or register to our website using your e-mail address and password.
Hover the mouse pointer on the
SUPPORT
tab at the top.
Click on
Code Downloads & Errata
.
Enter the name of the book in the
Search
box.
Select the book for which you're looking to download the code files.
Choose from the drop-down menu where you purchased this book from.
Click on
Code Download
.
You can also download the code files by clicking on the Code Files button on the book's webpage at the Packt Publishing website. This page can be accessed by entering the book's name in the Search box. Please note that you need to be logged in to your Packt account.
Once the file is downloaded, please make sure that you unzip or extract the folder using the latest version of:
WinRAR / 7-Zip for Windows
Zipeg / iZip / UnRarX for Mac
7-Zip / PeaZip for Linux
The code bundle for the book is also hosted on GitHub at https://github.com/PacktPublishing/Building-RESTful-Web-Services-with-Go. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!
Downloading the color images of this book
We also provide you with a PDF file that has color images of the screenshots/diagrams used in this book. The color images will help you better understand the changes in the output. You can download this file from https://www.packtpub.com/sites/default/files/downloads/BuildingRESTfulWebServiceswithGo_ColorImages.pdf.
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books-maybe a mistake in the text or the code-we would be grateful if you could report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/submit-errata, selecting your book, clicking on the Errata Submission Form link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded to our website or added to any list of existing errata under the Errata section of that title.
To view the previously submitted errata, go to https://www.packtpub.com/books/content/support and enter the name of the book in the search field. The required information will appear under the Errata section.
Piracy
Piracy of copyrighted material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works in any form on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.
Please contact us at [email protected] with a link to the suspected pirated material.
We appreciate your help in protecting our authors and our ability to bring you valuable content.
Questions
If you have a problem with any aspect of this book, you can contact us at [email protected], and we will do our best to address the problem.
Getting Started with REST API Development
A web service is a communication mechanism defined between different computer systems. Without web services, custom peer-to-peer communication becomes cumbersome and platform specific. It is like a hundred different kinds of things that the web needs to understand and interpret. If computer systems align with the protocols that the web can understand easily, it is a great help. A web service is a software system designed to support interoperable machine-to-machine interaction over a network, World Wide Web Consortium (W3C), https://www.w3.org/TR/ws-arch/.
Now, in simple words, a web service is a road between two endpoints where messages are transferred smoothly. Here, this transfer is usually one way. Two individual programmable entities can also communicate with each other through their own APIs. Two people communicate through language. Two applications communicate through the Application Programming Interface (API).
The reader might be wondering; what is the importance of the API in the current digital world? The rise of the Internet of Things (IoT) made API usage heavier than before. Consciousness about the API is growing day by day, and there are hundreds of APIs that are being developed and documented all over the world every day. Notable major businesses are seeing futures in the API as a Service (AAAS). A bright example is Amazon Web Services (AWS). It is a huge success in the cloud world. Developers write their own applications using the REST API provided by the AWS.
A few more hidden use cases are from travel sites like Ibibo and Expedia, which fetch real-time prices by calling the APIs of third-party gateways and data vendors. Web services are often charged these days.
Topics to be covered in this chapter are:
The different Web Services available
Representational State Transfer (
REST
) architecture in detail
Introduction to Single Page Applications (
SPA
) with REST
Setting up a Go project and running a development server
Building our first service for finding Roman numerals
Using Gulp to auto-compile Go code
Types of web services
There are many types of web services which have evolved over time. Prominent ones are :
SOAP
UDDI
WSDL
REST
Out of these, SOAP became popular in the early 2000s, when XML was on the top wave. The XML data format is used by various distributed systems to communicate with each other. SOAP is too complex to implement. Criticizers of SOAP point out how bulky the SOAP HTTP request is.
A SOAP request usually consists of these three basic components:
Envelope
Header
Body
Just to perform an HTTP request and response cycle, we have to attach a lot of additional data in SOAP. A sample SOAP request looks like this:
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetLastTradePrice xmlns:m="Some-URI">
<symbol>DIS</symbol>
</m:GetLastTradePrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This is a standard example of SOAP from the W3C standard (https://www.w3.org/TR/2000/NOTE-SOAP-20000508/). If we observe carefully, it is in XML format, with special tags specifying the envelope and body. Since XML operates on a lot of namespaces to function, additional information comes into play.
REST API
The name Representational state transfer (REST) was coined by Roy Fielding from the University of California. It is a very simplified and lightweight web service compared to SOAP. Performance, scalability, simplicity, portability, and modifiability are the main principles behind the REST design.
The REST API allows different systems to communicate and send/receive data in a very simple way. Each and every REST API call has a relation between an HTTP verb and the URL. The resources in the database in an application can be mapped with an API endpoint in the REST.
When you are using a mobile app on your phone, your phone might be secretly talking to many cloud services to retrieve, update, or delete your data. REST services have a huge impact on our daily lives.
REST is a stateless, cacheable, and simple architecture that is not a protocol but a pattern.
Characteristics of REST services
These are the main properties that make REST simple and unique compared to its predecessors:
Client-server based architecture:
This architecture is most essential for the modern web to communicate over HTTP. A single client-server may look naive initially, but many hybrid architectures are evolving. We will discuss more of these shortly.
Stateless:
This is the most important characteristic of a REST service. A REST HTTP request consists of all the data needed by the server to understand and give back the response. Once a request is served, the server doesn't remember if the request has arrived after a while. So the operation will be a stateless one.
Cacheable
: Many developers think a technology stack is blocking their web application or API. But in reality, their architecture is the reason. The database can be a potential tuning piece in a web application. In order to scale an application well, we need to cache content and deliver it as a response. If the cache is not valid, it is our responsibility to bust it. REST services should be properly cached for scaling.
Scripts on demand:
Have you ever designed a REST service which serves the JavaScript files and you execute them on the fly? This code on demand is also the main characteristic REST can provide. It is more common to request scripts and data from the server.
Multiple layered system:
The REST API can be served from multiple servers. One server can request the other, and so forth. So when a request comes from the client, request and response can be passed between many servers to finally supply a response back to the client. This easily implementable multi-layered system is always a good strategy for keeping the web application loosely coupled.
Representation of resources:
The REST API provides the uniform interface to talk to. It uses a
Uniform Resource Identifier
(
URI
) to map the resources (data). It also has the advantage of requesting a specific data format as the response. The Internet Media Type
(MIME type) can tell the server that the requested resource is of that particular type.
Implementational freedom:
REST is just a mechanism to define your web services. It is an architectural style that can be implemented in multiple ways. Because of this flexibility, you can create REST services in the way you wish to. Until it follows the principles of REST, your server has the freedom to choose the platform or technology.
REST verbs and status codes
REST verbs specify an action to be performed on a specific resource or a collection of resources. When a request is made by the client, it should send this information in the HTTP request:
REST verb
Header information
Body (optional)
As we mentioned previously, REST uses the URI to decode its resource to be handled. There are quite a few REST verbs available, but six of them are used frequently. They are as follows:
GET
POST
PUT
PATCH
DELETE
OPTIONS
If you are a software developer, you will be dealing with these six most of the time. The following table explains the operation, target resource, and what happens if the request succeeds or fails:
REST Verb
Action
Success
Failure
GET
Fetches a record or set of resources from the server
200
404
OPTIONS
Fetches all available REST operations
200
-
POST
Creates a new set of resources or a resource
201
404, 409
PUT
Updates or replaces the given record
200, 204
404
PATCH
Modifies the given record
200, 204
404
DELETE
Deletes the given resource
200
404
The numbers in the Success and Failure columns of the preceding table are HTTP status codes. Whenever a client initiates a REST operation, since REST is stateless, the client should know a way to find out whether the operation was successful or not. For that reason, HTTP has status codes for the response. REST defines the preceding status code types for a given operation. This means a REST API should strictly follow the preceding rules to achieve client-server communication.
All defined REST services have the following format. It consists of the host and API endpoint. The API endpoint is the URL path which is predefined by the server. Every REST request should hit that path.
Let us look at all the verbs in more detail. The REST API design starts with the defining of operations and API endpoints. Before implementing the API, the design document should list all the endpoints for the given resources. In the following section, we carefully observe the REST API endpoints using PayPal's REST API as a use case.
GET
A GET method fetches the given resource from the server. To specify a resource, GET uses a few types of URI queries:
Query parameters
Path-based parameters
In case you didn't know, all of your browsing of the web is done by performing a GET request to the server. For example, if you type www.google.com, you are actually making a GET request to fetch the search page. Here, your browser is the client and Google's web server is the backend implementer of web services. A successful GET operation returns a 200 status code.
Examples of path parameters:
Everyone knows PayPal. PayPal creates billing agreements with companies. If you register with PayPal for a payment system, they provide you with a REST API for all your billing needs. The sample GET request for getting the information of a billing agreement looks like this: /v1/payments/billing-agreements/agreement_id.
Here, the resource query is with the path parameter. When the server sees this line, it interprets it as I got an HTTP request with a need for agreement_id from the billing agreements. Then it searches through the database, goes to the billing-agreements table, and finds an agreement with the given agreement_id. If that resource exists it sends the details to copy back in response (200 OK). Or else it sends a response saying resource not found (404).
Using GET, you can also query a list of resources, instead of a single one like the preceding example. PayPal's API for getting billing transactions related to an agreement can be fetched with /v1/payments/billing-agreements/transactions. This line fetches all transactions that occurred on that billing agreement. In both, the case's data is retrieved in the form of a JSON response. The response format should be designed beforehand so that the client can consume it in the agreement.
Examples of query parameters are as follows:
Query parameters are intended to add detailed information to identify a resource from the server. For example, take this sample fictitious API. Let us assume this API is created for fetching, creating, and updating the details of the book. A query parameter based
GET
request will be in this format:
/v1/books/?category=fiction&publish_date=2017
The preceding URI has few query parameters. The URI is requesting a book from the book's resource that satisfies the following conditions:
It should be a fiction book
The book should have been published in the year 2017
Get all the fiction books that are released in the year 2017 is the question the client is posing to the server.
Path vs Query parameters—When to use them? It is a common rule of thumb that Query parameters are used to fetch multiple resources based on the query parameters. If a client needs a single resource with exact URI information, it can use Path parameters to specify the resource. For example, a user dashboard can be requested with Path parameters and fetch data on filtering can be modeled with Query parameters.
POST, PUT, and PATCH
The POST method is used to create a resource on the server. In the previous book's API, this operation creates a new book with the given details. A successful POST operation returns a 201 status code. The POST request can update multiple resources: /v1/books.
The POST request has a body like this:
{"name" : "Lord of the rings", "year": 1954, "author" : "
J. R. R. Tolkien
"}
This actually creates a new book in the database. An ID is assigned to this record so that when we GET the resource, the URL is created. So POST should be done only once, in the beginning. In fact, Lord of the Rings was published in 1955. So we entered the published date incorrectly. In order to update the resource, let us use the PUT request.
The PUT method is similar to POST. It is used to replace the resource that already exists. The main difference is that PUT is idempotent. A POST call creates two instances with the same data. But PUT updates a single resource that already exists:
/v1/books/1256
with body that is JSON like this:
{"name" : "Lord of the rings", "year": 1955, "author" : "J. R. R. Tolkien"}
1256 is the ID of the book. It updates the preceding book by year:1955. Did you observe the drawback of PUT? It actually replaced the entire old record with the new one. We needed to change a single column. But PUT replaced the whole record. That is bad. For this reason, the PATCH request was introduced.
The PATCH method is similar to PUT, except it won't replace the whole record. PATCH, as the name suggests, patches the column that is being modified. Let us update the book 1256 with a new column called ISBN:
/v1/books/1256
with the JSON body like this:
{"isbn" : "0618640150"}
It tells the server, Search for the book with id 1256. Then add/modify this column with the given value.
DELETE and OPTIONS
The DELETE API method is used to delete a resource from the database. It is similar to PUT but without any body. It just needs an ID of the resource to be deleted. Once a resource gets deleted, subsequent GET requests return a 404 not found status.
The OPTIONS API method is the most underrated in the API development. Given the resource, this method tries to know all possible methods (GET, POST, and so on) defined on the server. It is like looking at the menu card at a restaurant and then ordering an item which is available (whereas if you randomly order a dish, the waiter will tell you it is not available). It is best practice to implement the OPTIONS method on the server. From the client, make sure OPTIONS is called first, and if the method is available, then proceed with it.
Cross-Origin Resource Sharing (CORS)
The most important application of this OPTIONS method is Cross-Origin Resource Sharing (CORS). Initially, browser security prevented the client from making cross-origin requests. It means a site loaded with the URL www.foo.com can only make API calls to that host. If the client code needs to request files or data from www.bar.com, then the second server, bar.com, should have a mechanism to recognize foo.com to get its resources.
This process explains the CORS:
foo.com
requests the
OPTIONS
method on
bar.com
.
bar.com
sends a header like
Access-Control-Allow-Origin: http://foo.com
in response to the client.
Next,
foo.com
can access the resources on
bar.com
without any restrictions that call any
REST
method.
If bar.com feels like supplying resources to any host after one initial request, it can set Access control to * (that is, any).
The following is the diagram depicting the process happening one after the other:
Types of status codes
There are a few families of status codes. Each family globally explains an operation status. Each member of that family may have a deeper meeting. So a REST API should strictly tell the client what exactly happened after the operation. There are 60+ status codes available. But for REST, we concentrate on a few families of codes.
2xx family (successful)
200 and 201 fall under the success family. They indicate that an operation was successful. Plain 200 (Operation Successful) is a successful CRUD Operation:
200
(
Successful Operation
) is the most common type of response status code in REST
201
(
Successfully Created
)
is returned when a
POST
operation successfully creates a resource on the server
204
(
No content
) is issued when a client needs a status but not any data back
3xx family (redirection)
These status codes are used to convey redirection messages. The most important ones are 301 and 304:
301
is issued when a resource is moved permanently to a new URL endpoint. It is essential when an old API is deprecated. It returns the new endpoint in the response with the 301 status. By seeing that, the client should use the new URL in response to achieving its target.
The
304
status code indicates that content is cached and no modification happened for the resource on the server. This helps in caching content at the client and only requests data when the cache is modified.
