API design guide

Introduction This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide that Google follows when designing Cloud APIs and other Google APIs. This design guide is shared here to inform outside developers and to make it easier for us all to work together. Cloud Endpoints developers may find this guide particularly useful when designing gRPC APIs, and we strongly recommend such developers use these design principles. However, we don't mandate its use. You can use Cloud Endpoints and gRPC without following the guide. This guide applies to both REST APIs and RPC APIs, with specific focus on gRPC APIs. gRPC APIs use Protocol Buffers to define their API surface and API Service Configuration to configure their API services, including HTTP mapping, logging, and monitoring. HTTP mapping features are used by Google APIs and Cloud Endpoints gRPC APIs for JSON/HTTP to Protocol Buffers/RPC transcoding. This guide is a living document and additions to it will be made over time as new style and design patterns are adopted and approved. In that spirit, it is never going to be complete and there will always be ample room for the art and craft of API design.

Conventions Used in This Guide The requirement level keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document are to be interpreted as described in RFC 2119. In this document, such keywords are highlighted using bold font.
Sections

Resource-oriented Design For information about implementing resource-oriented design for RPC and REST APIs, see AIP-121. Resource Names For information about resource names, see AIP-122. Standard Methods

For general information about methods, see AIP-130. For information about standard methods, see the following AIPs:

For Get, see AIP-131
For List, see AIP-132
For Create, see AIP-133
For Update, see AIP-134
For Delete, see AIP-135
Custom Methods For information about custom methods, see AIP-136.
Additional topics For information about the following topics, see their related AIPs. For Standard fields, see AIP-148
For Errors, see AIP-193
For Design patterns, see AIP guidance on design patterns
For Inline API documentation, see AIP-192
For Using proto3, see the Syntax section of AIP-191
For Versioning, see AIP-185
For Backward compatibility, see AIP-180
For File structure, see the File Layout section of AIP-191
For a Glossary of terms, see AIP-9
For information about the following topics, see their related pages in this guide.
Naming Conventions Directory Structure 7 Tagging: IsTagged 8 Remarketing: IsRemarketing 9 UserInterestTargeting: IsUserInterestTargeted 12 ExpandingDirection: ExpandingNone 13 ExpandingDirection: ExpandingUp 14 ExpandingDirection: ExpandingDown 15 ExpandingDirection: ExpandingLeft 16 ExpandingDirection: ExpandingRight 17 ExpandingDirection: ExpandingUpLeft 18 ExpandingDirection: ExpandingUpRight 19 ExpandingDirection: ExpandingDownLeft 20 ExpandingDirection: ExpandingDownRight 25 ExpandingDirection: ExpandingUpOrDown 26 ExpandingDirection: ExpandingLeftOrRight 27 ExpandingDirection: ExpandingAnyDiagonal 28 ExpandingAction: RolloverToExpand 30 InstreamVastVideoType: Vpaid 32 MraidType: MRAID 47 RichMediaCapabilityType: RichMediaCapabilitySSL 70 NativeEligibility: Native Eligible 72 NativeEligibility: Native Not Eligible 105 Rendering: Sizeless AdX 155 Rendering: Playable 10001 Vehicles 10002 Family & Community 10003 Real Estate 10004 Business & Industrial 10005 Beauty & Personal Care 10006 Occasions & Gifts 10007 Internet & Telecom 10009 Home & Garden 10010 Food & Groceries 10011 Health 10012 Finance 10013 Arts & Entertainment 10014 Sports & Fitness 10015 Hobbies & Leisure 10016 Jobs & Education 10017 Travel & Tourism 10018 Law & Government 10019 Computers & Consumer Electronics 10020 Dining & Nightlife 10021 Apparel 10024 Motor Vehicles 10026 Vehicle Parts & Accessories 10027 Boats & Watercraft 10030 Baby, Parenting & Family 10031 Romance & Relationships 10032 Rental Listings 10035 Relocation & Household Moving 10039 Property Development 10040 Real Estate Agents & Brokerages 10042 Real Estate Listings 10047 Skin Care 10048 Tanning & Sun Care 10049 Spa & Medical Spa 10050 Anti-Aging 10052 Baby Care & Hygiene 10054 Make-Up & Cosmetics 10055 Hair Care 10057 Perfumes & Fragrances 10058 Shaving & Grooming 10059 Oral Care 10060 Hygiene & Toiletries 10061 Face Care 10080 Tobacco 10081 Household Supplies 10082 Food 10083 Beverages 10084 Online Grocery Shopping & Grocery Delivery 10085 Health Conditions & Concerns 10086 Nutrition & Dieting 10087 Medical Devices, Equipment & Supplies 10088 Biotech & Pharmaceutical 10089 Pharmacy 10090 Professional Medical Resources 10091 Health Care Services 10092 Financial Planning & Management 10093 Banking 10094 Money Transfer & Wire Services 10095 Investing 10096 Business Finance 10097 Credit & Lending 10098 Business News & Media 10099 Grants, Scholarships & Financial Aid 10102 Insurance 10103 TV & Video 10105 Entertainment Industry 10106 Humor & Jokes 10108 News, Media & Publications 10109 Music & Audio 10111 Events, Shows & Cultural Attractions 10112 Books & Literature 10113 Camping & Outdoor Recreation 10115 Sports & Fitness Apparel 10116 Sports Fan Gear & Apparel 10117 Boating & Water Recreation 10118 Sports Nutrition Supplements 10120 Sports Equipment Rental Services 10121 Sporting Goods 10123 Fitness 10125 Toys & Games 10127 Occult & Paranormal 10128 Cooking 10130 Pets & Animals 10131 Arts & Crafts 10132 Photo & Video 10133 Ancestry & Genealogy 10135 Antiques & Collectibles 10137 Gambling 10141 Education & Training 10142 Accommodations 10144 Air Travel 10145 Tourist Attractions & Destinations 10146 Transportation & Excursions 10147 Last Minute Travel 10150 Specialty Travel 10151 Travel Booking Services 10153 Cruises & Cruise Services 10154 Vacation Packages 10159 Military 10160 Public Services 10163 Legal 10167 Consumer Electronics 10168 Computers 10169 Restaurants 10171 Jewelry 10176 Clothing 10177 Footwear 10182 Motorcycles 10183 Campers & RVs 10185 Cars & Trucks 10191 Driving Instruction & Driver Education 10193 Vehicle Repair & Maintenance 10206 Vehicle Tires & Tire Parts 10209 Car Parts & Accessories 10224 Alcohol & Substance Abuse 10227 Social Issues & Advocacy 10231 Faith & Belief 10235 Baby 10236 Parenting & Family 10238 Divorce & Separation 10273 Design & Engineering 10282 Building Construction & Maintenance 10294 Scientific Equipment & Services 10295 Energy Industry 10296 Business Management Software 10299 Security Equipment & Services 10300 Office 10301 Food Service Industry 10302 Industrial Electronics 10306 Plant & Facility 10307 Commercial & Industrial Printing 10338 Shampoos & Conditioners 10355 Antiperspirants, Deodorants & Body Spray 10356 Feminine Hygiene Products 10362 Flower Arrangements 10364 Cards & Greetings 10365 Gifts 10366 Funerals & Bereavement 10368 Parties & Party Supplies 10369 Weddings 10399 Residential Cleaning 10404 Home Improvement & Maintenance 10405 Home Decor & Interior Decorating 10406 Yard, Garden & Patio 10407 Water Filters 10410 Kitchen & Dining 10411 Home Safety & Security 10412 Home Appliances 10413 Home Furniture 10418 Home Heating & Cooling 10419 Lights & Lighting 10421 Paper Towels & Household Paper Products 10422 Food Wraps & Food Storage 10423 Household Cleaning Products 10431 Sauces 10432 Baked Goods 10434 Baking Ingredients 10435 Snack Foods 10436 Desserts 10437 Meat & Poultry 10438 Candy, Gum & Mints 10439 Breakfast Foods 10440 Dairy & Non-Dairy Alternatives 10444 Non-Alcoholic Beverages 10445 Alcoholic Beverages 10446 Allergy & Sinus 10449 Eating Disorders 10452 Cold Sores 10453 Smoking & Smoking Cessation 10454 Warts 10456 Digestive Health & Disorders 10460 Vision 10464 Cancer & Cancer Treatment 10465 Geriatrics & Aging 10466 Hemorrhoids 10467 Hepatitis 10468 Infectious Diseases & Viruses 10469 Learning & Developmental Disabilities 10473 Skin Conditions & Skin Health 10474 Neurological Conditions 10475 Heart Health 10476 AIDS & HIV 10479 Arthritis 10480 Men's Health 10481 Hearing Loss 10483 Blood Sugar & Diabetes 10486 Headache & Pain Management 10487 Dental Health 10488 Mental Health 10491 Diets & Diet Programs 10493 First Aid Supplies 10494 Mobility Equipment & Accessories 10504 Medical Research 10505 Professional Health Care Education 10507 Alternative & Natural Medicine 10508 Plastic Surgery 10509 Laboratory Testing & Medical Diagnostic Services 10511 Physical Rehabilitation 10515 Vision Services 10518 Mental Health Services 10519 Orthopedics & Sports Medicine 10520 Hospitals & Health Clinics 10531 Real Estate Investments 10536 Student Loans 10539 Life Insurance 10544 Health Insurance 10547 Property Insurance 10550 Vehicle Insurance 10557 TV Shows & Programs 10566 TV Broadcasting 10570 Radio 10578 Travel Media & Publications 10584 Celebrities & Entertainment News 10591 Music Streams & Downloads 10598 Fantasy Sports 10603 Ticket Sales & Exchanges 10609 Book Retailers 10611 E-Books 10615 Climbing 10616 Hiking 10619 Athletic Shoes 10628 Fishing 10645 Bicycles & Accessories 10648 Airsoft Equipment 10653 Golf Equipment 10666 Fitness Classes & Instruction 10668 Gyms & Gym Memberships 10669 Personal Training 10671 Toys 10672 Games 10679 Recipes 10683 Pet Food & Supplies 10691 Digital Cameras 10692 Video Cameras & Camcorders 10693 Photo & Video Accessories 10746 Job Listings 10752 Online Education & Degree Programs 10754 Standardized & Admissions Tests 10756 Reference Materials & Resources 10757 Language Education 10758 Training & Certification 10759 Vocational Training & Trade Schools 10761 Tutoring Services 10763 Colleges, Universities & Post-Secondary Education 10769 Hotels, Motels & Resorts 10770 Vacation Rentals 10776 Luggage 10778 Airline Tickets, Fares & Flights 10782 Car Rental Services 10783 Bus & Rail Services 10784 Taxi Services 10829 Public Utilities 10857 Immigration Law 10872 Consumer Electronic Accessories 10873 Home Audio & Video 10876 Wireless Devices 10877 Portable Media Devices 10878 Telephony 10880 GPS & Navigation 10881 Car Audio & Video 10883 Computer Hardware 10885 Software 10886 Computer Accessories 10889 Cuisines 10890 Dine-In Restaurants 10891 Fast Food Restaurants 10899 Watches & Watch Accessories 10913 Underwear 10920 Formal Wear 10923 Plus Size Clothing 10925 Sleepwear 10963 Hybrid & Alternative Vehicles 11005 Work & Labor Issues 11006 Reproductive Rights 11008 Environmental Activism 11009 Animal Rights Activism 11020 Baby Diapering & Toilet Training 11022 Baby Feeding 11028 Maternity & New Parent 11093 Accounting & Auditing 11099 Office & Facilities Management 11141 Commercial & General Contracting 11270 Project Management Software 11284 HVAC & Climate Control 11287 Hardware Tools & Accessories 11321 Security Weapons 11339 Office Appliances 11368 Graphics & Multimedia Software 11412 Hand & Body Soaps & Cleansers 11491 Internet Service Plans 11493 Web Design & Development 11496 Social Networks & Online Communities 11504 Web Hosting 11511 Mobile Phone Plans 11527 Home Appliance Service & Repair 11541 Outdoor Cooking Equipment & Accessories 11567 Major Kitchen Appliances 11589 Bedding & Linens 11597 Dish Detergents 11598 Air Fresheners & Deodorizers 11604 Frozen Foods 11629 Breakfast Cereals 11642 Soft Drinks 11643 Juice 11644 Coffee 11645 Tea 11647 Energy Drinks 11648 Sports Drinks 11649 Wine 11650 Liquor 11651 Beer 11669 Weight Loss Products 11695 Alzheimer's Disease 11710 Acne 11719 High Blood Pressure 11721 High Cholesterol 11772 Vitamins & Supplements 11773 Drugs & Medications 11780 Chiropractors & Chiropractic 11783 Cosmetic & Aesthetic Plastic Surgery 11793 Wellness Therapy & Massage 11813 Private Banking 11814 Online Banking 11816 Debit & Check Cards 11818 Fixed Deposit Accounts & Certificates 11819 Brokerages & Day Trading 11820 Investor Relations & Venture Capital 11824 Retirement Investments 11825 Spread Betting 11827 Securities 11828 Mutual Funds 11831 Currencies & Foreign Exchange 11838 Credit Reports & Reporting Services 11839 Debt Management & Consolidation 11840 Unsecured Credit & Lending 11841 Loans 11842 Credit Cards 11870 Dining & Nightlife Reviews, Guides & Listings 11883 Sports Event Tickets & Ticketing Services 11901 Sports Team Jerseys 11917 Swimwear 11929 Building Toys 11937 Children's Dolls, Dress-Up Toys & Costumes 11939 Radio Controlled Toys & Accessories 11940 Educational Toys 11941 Action Figures 11942 Online Games & Puzzles 11943 Card Games 11944 Puzzles & Brain Teasers 11945 Roleplaying Games 11946 Strategy Games 11948 Board Games 11949 Arcade & Coin-op Games 11950 Video Games, Consoles & Accessories 11963 Pet Food & Treats 11964 Pet Medications 11965 Flea & Tick Control Products 11980 Pet Breeding 11987 Fiber Craft 12066 Resorts 12067 Hotels 12083 Bus Services 12084 Rail Services 12110 Renewable & Alternative Energy 12113 Oil & Gas 12138 Speakers 12143 Televisions 12161 Mobile Phones 12184 Computer Networking Devices 12187 Laptop Computers 12204 Internet Software & Web Goodies 12206 Educational Software 12209 Business & Productivity Software 12228 Pizzerias & Pizza Delivery 12240 Shirts, Tops & Blouses 12261 Sunglasses 12263 Handbags & Purses 12387 Tax Preparation & Planning 12494 Medical Diagnostic Equipment & Monitoring Devices 12590 Power Tools 12701 Photo Software 12757 RSS Feeds & Aggregators 12766 Cable TV 12767 Satellite TV 12777 Garden Structures 12795 Washers & Dryers 12797 Vacuum Cleaners & Accessories 12828 Laundry Detergents 12849 Air Cleaners & Filters 12864 Weight Loss Drugs & Medications 12865 Weight Loss Supplements 12866 Eyeglass Frames 12867 Contact Lenses & Accessories 12926 Multi-Vitamins 12950 401(K)s 12952 IRAs 12956 Commercial Lending 12957 Auto Financing 12960 Home Loans & Mortgages 12961 Personal Lending & Borrowing 12997 Massive Multiplayer Online Games 13092 Network Security Software 13094 Email & Messaging 13116 Jerseys & Knit Shirts 13250 Pest & Weed Control 13260 Mattresses 13283 Commercial Mortgages 13284 Auto Leasing 13286 Title Loans 13289 Interest Only Mortgages 13291 Government Mortgages 13292 Buy-To-Let Mortgages 13293 Fixed Rate Mortgages 13296 Home Equity Loans & Lines of Credit 13299 Home Refinancing Loans 13300 Payday & Emergency Loans 13301 Personal Loans & Lines of Credit 13314 Anti-Virus Software 13369 Gene Research 13372 Screensavers & Digital Wallpaper 13374 Trees, Plants & Shrubs 13376 Video Game Consoles 13377 Computer & Video Games 13381 Mobile Phones & Accessories 13388 Visual Art & Design 13405 Prizes & Competitions 13406 Web Browsers 13417 Movies & Films 13418 Internet 13419 Phone Plans 13422 Body Art 13423 Guns & Firearms 13425 Fun & Trivia 13426 Weather 13427 Music Education & Instruction 13428 Multi-tools & Pocket Knives 13432 Translation 13439 Nightclubs, Bars & Music Clubs 13459 Stocks 13464 Industrial Goods & Manufacturing 13469 Astrology & Horoscopes 13470 Psychics & Fortune Telling 13472 Christianity 13473 Islam 13474 Buddhism 13475 Hinduism 13476 Judaism 13479 Scientology 13489 Fun Tests & Silly Surveys 13491 Chemical Industry 13493 Special Occasions 13496 Theme Parks 13509 Holidays & Seasonal Events 13513 Graduate Programs 13525 Horror Films 13530 Arts & Entertainment Awards 13536 Film & TV Industry 13566 Offbeat 13567 Edgy & Bizarre 13584 Adventure Games 13585 Casual Games 13586 Driving & Racing Games 13588 Music & Dance Games 13589 Shooter Games 13590 Simulation Games 13591 Sports Games 13596 Photographic & Digital Arts 13605 Sports 13606 American Football 13608 Soccer 13609 Basketball 13610 Baseball 13611 Hockey 13612 Hunting & Shooting 13620 Winter Sports 13633 Combat Sports 13647 Newspapers 13655 Vehicle Dealers 13656 Car Dealers 13657 Boat & Yacht Sales & Brokers 13658 Gardening 13680 Sweepstakes, Product Promotions & Giveaways 13686 Attorneys & Law Firms 13710 People Search 13714 Used Motor Vehicles 13716 Public Records 13722 Cleansing & Detoxification 13725 Web Portals 13740 Halloween & October 31st 13760 Cartoons 13767 Poker & Casino Games 13768 Domain Names & Domain Name Registration 13778 Men's Clothing 13779 Women's Clothing 13780 Children's Clothing 13794 Childrens Games & Activities 13797 Building Materials & Supplies 13801 Audio Books 13834 Family & Children's Games 13863 Action & Platform Games 13934 Mobile App Utilities 13935 Mobile System Management Apps 13936 Flashlight Apps 13937 Location Tracking Apps 13938 Network Connectivity Apps 13939 Mobile Screen & App Locks 13940 Battery Management Apps 13941 File Manager Apps 13942 Mobile Task & App Management 13945 Word Games 0 Ad has no restricted categories 32 Gambling 33 Alcohol 3 Unicast 42 BlueKai 79 revenue cloud 138 Reddion 144 Campaign Monitor 230 Unicast 237 Reddion 238 Media Intelligence Platform (Aggregate Knowledge) 242 Lotame Solutions Inc. 255 Accuen 263 AddThis, Inc 267 DataLogix, Inc. 331 Avail Intelligence 332 Audience Manager 342 Adledge 414 Batch Media Gmbh 445 Project SunBlock 474 Integral Ad Science Firewall 475 ComScore (AdXpose): Ad Swapping 477 ComScore (AdXpose): Ad Swapping 481 eXelate Inc. 485 VoiceFive (ComScore) 486 Adloox: Ad Swapping 489 revenue cloud 490 Adledge: Ad Swapping 523 Spongecell - Expandable 529 Eyeota Limited 537 Public Eye 542 Bizo Inc 543 VisualDNA (Imagini) 550 AdYapper, Inc. 562 Experian 564 NODDINGTON TECHNOLOGIES LIMITED 566 Spark Flow S.A. 572 Webtrekk GmbH 573 Fabric Worldwide Inc 574 LiveRamp, Inc. 575 Krux Digital, Inc. 623 Human Demand 698 GET IT Mobile, Inc 704 GlobalWebIndex 745 adverserve digital advertising services 767 SOCIETE FRANCAISE DU RADIOTELEPHONE 776 Spark Flow S.A. 780 Where 2 Get It, Inc. 785 Scrutineer 793 Semasio GmbH 797 ADmantX, SPA 798 Nielsen Catalina Solutions 806 Sociomantic Expandable 808 Hatena Co., Ltd 818 Redbranch, Inc. (dba Fraudlogix) 826 AmberData LLC 828 Crutchfield New Media, LLC 832 The ADEX 880 Navegg 884 nugg.ad AG 885 OnAudience.com 889 Netscore 2380 Data Exchanger 4374 TailTarget 4458 Yieldlab 4461 Sharethrough 4463 Captify 4513 Rippll 4538 BannerConnect DMP 4625 Turbo 4648 Squeezely DMP 4651 Dianomi 4680 Signals 4697 geolad GmbH 38523 MiQ Digital LTD 39523 ADMASTERS SOLUÇÕES DE MARKETING DIGITAL LTDA 40824 CarbonTag 41423 TradPlus 44523 Six Dee Netad Solutions Pvt Ltd 56423 TouchTown Media