Brajesh De

API Management

An Architect’s Guide to Developing and Managing APIs for Your Organization

First Edition

Brajesh De

Bangalore, Karnataka, India

Any source code or other supplementary material referenced by the author in this book is available to readers on GitHub via the book’s product page, located at www.apress.com/978-1-4842-1306-3 . For more detailed information, please visit http://www.apress.com/source-code .

ISBN 978-1-4842-1306-3

e-ISBN 978-1-4842-1305-6

DOI 10.1007/978-1-4842-1305-6

Library of Congress Control Number: 2017935977

© Brajesh De 2017

This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed.

Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights.

While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein.

Printed on acid-free paper

Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail [email protected], or visit www.springeronline.com. Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation.

Dedicated to my family for their constant encouragement and support

Acknowledgments

First and foremost, I would like to thank my wife, Roopa, for her constant love, support and sacrifice throughout the lengthy process of authoring this book. She has been my source of encouragement and inspiration from start to finish. Her timely reminders helped me to pen down each chapter at a steady pace. My son Bornik deserves special thanks for his subtle yet valuable inputs, which helped me to plan the contents of each chapter. Without his patience and sacrifice, getting time to write this book would have been an uphill task. Last but not the least, no words can express the love and blessings of my parents, Bamapada and Minakshi; without them, I could not have authored this book.

I would also like to thank Celestin Suresh John, Prachi Mehta, Baby Gopalakrishnan, Mercy Thomas and all the editors of this book for their support, review comments and input that helped to constantly improve the quality of each chapter.

Contents

  1. Chapter 1:​ Introduction to APIs
    1. The Evolution of APIs
    2. APIs Are Different from Web Sites
    3. Defining an API and Its Characteristics
    4. Types of APIs
    5. Examples of Popular APIs
    6. The Difference Between a Web Service and a Web API
    7. How Are APIs Different from SOA?​
    8. The API Value Chain
    9. Business Models for APIs
  2. Chapter 2:​ API Management
    1. Secure, Reliable, and Flexible Communication
      1. The API Gateway
    2. API Auditing, Logging and Analytics
      1. API Analytics
    3. Developer Enablement for APIs
      1. Developer Portal
    4. API Lifecycle Management
      1. API Creation
      2. API Publication
      3. Version Management
      4. Change Notification
      5. Issue Management
  3. Chapter 3:​ Designing a RESTful API Interface
    1. REST Principles
      1. Uniform Interface
      2. Client-Server
      3. Stateless
      4. Cache
      5. Layered Systems
      6. Code on Demand
    2. Designing a RESTful API
      1. Identification of Resources
      2. Manipulation of Resources through Representation
      3. Self-Descriptive Messages
      4. Hypermedia as the Engine of Application State (HATEOAS)
    3. Resource Identifier Design Using URIs
      1. Resource Naming Conventions
      2. Modelling Resources and Subresources
      3. Best Practices for Identifying REST API Resources
      4. URI Path Design
      5. URI Format
      6. Naming Conventions for URI Paths
    4. HTTP Verbs for RESTful APIs
      1. GET
      2. POST
      3. PUT
      4. DELETE
      5. PATCH
      6. OPTIONS
      7. HEAD
      8. Idempotent and Safe Methods
    5. HTTP Status Code
    6. Resource Representation Design
    7. Hypermedia Controls and Metadata
      1. Accept (Client Request Header)
      2. Accept-Charset (Client Request Header)
      3. Authorization (Client Request Header)
      4. Host (Client Request Header)
      5. Location (Server Response Header)
      6. ETag (Server Response Header)
      7. Cache-Control (General Header)
      8. Content-Type (General Header)
    8. Header Naming Conventions
    9. Versioning
    10. Querying, Filtering, and Pagination
      1. Limiting via Query-String Parameters
      2. Filtering
    11. The Richardson Maturity Model
      1. Level 0:​ Swamp of POX (Plain Old XML)
      2. Level 1:​ Resources
      3. Level 2:​ HTTP Verbs
      4. Level 3:​ Hypermedia Controls
  4. Chapter 4:​ API Documentation
    1. The Importance of API Documentation
    2. Audience for API Documentation
    3. Model for API Documentation
      1. Title
      2. Endpoint
      3. Method
      4. URL Parameters
      5. Message Payload
      6. Header Parameters
      7. Response Code
      8. Error Codes and Responses
      9. Sample Calls
      10. Tutorials and Walk-throughs
      11. Service-Level Agreements
    4. API Documentation Standards:​ Swagger, RAML, and API Blueprint
      1. Swagger
      2. RAML
      3. API Blueprint
      4. Comparing Swagger, RAML, and API Blueprint
    5. Other API Documentation Frameworks
  5. Chapter 5:​ API Patterns
    1. Best Practices for Building a Pragmatic RESTful API
    2. API Management Patterns
      1. API Facade Pattern
      2. API Throttling
      3. Caching
      4. Logging and Monitoring
      5. API Analytics
    3. API Security Patterns
      1. Common Forms of Attack
      2. API Risk Mitigation Best Practices
    4. API Deployment Patterns
      1. Cloud Deployment
      2. On-Premise Deployment
    5. API Adoption Patterns
      1. APIs for Internal Application Integration
      2. APIs for Business Partner Integration
      3. APIs for External Digital Consumers
      4. APIs for Mobile
      5. APIs for IoT
  6. Chapter 6:​ API Version Management
    1. API Versioning vs.​ Software Versioning
    2. The Need to Version APIs
    3. API Versioning Principles
      1. The API Version Should Not Break any Existing Clients
      2. Keep the Frequency of Major API Versions to a Minimum
      3. Make Backward-Compatible Changes and Avoid Making New API Versions
      4. API Versioning Should Not Be Directly Tied to Software Versioning
    4. Approaches to API Version Management
      1. Versions Using URLs
      2. Versions Using an HTTP Header
      3. Versions Using Query Parameters
      4. Versions Using a Host Name
      5. Handling Requests for Deprecated Versions
    5. API Version Lifecycle Management
  7. Chapter 7:​ API Security
    1. The Need for API Security
    2. API Security Threats
    3. API Authentication and Authorization
      1. API Keys
      2. Username and Password
      3. X.​509 Client Certificates and Mutual Authentication
      4. OAuth
      5. OpenID Connect
    4. Protecting Against Cyber Threats
      1. Injection Threats
      2. Insecure Direct Object Reference
      3. Sensitive Data Exposure
      4. Cross-Site Scripting (XSS)
      5. Cross-Site Resource Forgery (CSRF or XSRF)
      6. Bot Attacks
    5. Considerations for Designing an API Security Framework
    6. API Security Threat Model
    7. API Security Recommendations
  8. Chapter 8:​ API Monetization
    1. Which Digital Assets Can Be Monetized?​
    2. How to Increase Revenue Using APIs?​
      1. Increase Customer Channels
      2. Increase Customer Retention
      3. Upsell Premium and Value-Added Services
      4. Increase Affiliate Channels
      5. Increase Distribution Channels
    3. API Monetization Models
      1. Free Model
      2. Fee-Based Model (a.​k.​a.​ Developer Pays Model)
      3. Revenue-Sharing Model
    4. Monetization Concepts
      1. API Product
      2. API Package
      3. Rate Plan
      4. Billing Documents
      5. Monetization Reports
  9. Chapter 9:​ API Testing Strategy
    1. The Importance of API Testing
    2. Challenges in API Testing
    3. API Testing Considerations
      1. API Interface Specification Testing
      2. API Documentation Testing
      3. API Security Testing
    4. Testing API Gateway Configuration
    5. API Performance Testing
      1. Preparing for the Load Test
      2. Setting up for the Load Test
      3. API Performance Test Metrics
    6. Selecting The Right API Testing Tool
      1. Must-Have Features
      2. Nice-to-Have Features
      3. Common API Testing Tools
  10. Chapter 10:​ API Analytics
    1. The Importance of API Analytics
    2. API Analytics Stakeholders
    3. API Metrics and Reports
      1. Custom Analytics Reports
  11. Chapter 11:​ API Developer Portal
    1. The API Lifecycle
    2. Publishing and Sharing APIs
    3. The Importance of the API Developer Portal
    4. Supporting App Developers
      1. Invitations
      2. Social Forums
      3. Federated Developer Communities
    5. Types of Portal Users
    6. API Developer Portal Features
    7. The Relationship Between a Developer Portal and an API Gateway
  12. Chapter 12:​ API Governance
    1. The Scope of API Governance
    2. The Aim of API Governance
    3. API Governance Model
  13. Index

About the Author and About the Technical Reviewer

About the Author

A340883_1_En_BookFrontmatter_Figb_HTML.jpg

Brajesh De is a seasoned technology expert with over 18 years of experience in technology consulting, architecture, design and implementation of highly distributed and scalable application integration solutions using REST API, SOA and JEE technologies. He is an Accenture certified Senior Technology Architect. With specialization in API Management, he currently leads the API Management capability for Accenture’s India Development Center. Prior to joining Accenture, he has worked as a Principal Architect with Apigee, architecting API Management solutions for large enterprises in Telco domain. He has also worked with Dell, where he was responsible for SOA governance rollout and building integration solutions for Dell’s internal applications using SOA technologies. Before Dell he was working as a Senior Technical Architect with Wipro Technologies where he has been instrumental in building complex integration solution for their tier one clients.

Brajesh is also an experienced trainer, providing corporate training in advanced API and SOA technologies. He holds a B. Tech degree in Electrical Engineering from IIT-BHU, Varanasi. He was awarded the IIT BHU gold medal for securing the first position and first division in B.Tech. Electrical Engineering Examination, 1998.

About the Technical Reviewer

Chandresh Pancholi is SDE-3 at nnnow.com (Arvind Internet group). Prior to that, he worked with Flipkart Internet Pvt. Ltd. as a senior software developer. He has worked on multiple back-end frameworks, such as Spring, Dropwizard, Flask, Golang, and Spring Boot. Chandresh graduated from LNMIIT, Jaipur and received a master’s degree from BITS, Pilani. He is also a keen contributor to Apache open source foundations projects.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.117.8.216