[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"doc-seo-673532-105":3,"detail-sidebar-cat-0-en-105":81,"doc-detail-673532-en":130},{"code":4,"msg":5,"data":6},0,"ok",{"site_id":7,"language":8,"slug":9,"title":10,"keywords":11,"description":12,"schema_data":13,"social_meta":74,"head_meta":76,"extra_data":78,"updated_unix":80},105,"en","how-to-design-a-good-api-and-why-it-matters","How to Design a Good API and Why it Matters","","API design is presented as a strategic lever that can create lasting value or cause ongoing maintenance costs. The material explains why public APIs must be correct early, and how thinking in APIs improves modularity, reuse, and code quality. It outlines core characteristics of a good API, then guides requirements gathering, starting with short specifications, writing API-facing code early, and extending the same discipline to SPI plug-in interfaces.",{"@graph":14,"@context":73},[15,34,56],{"@type":16,"itemListElement":17},"BreadcrumbList",[18,23,27,31],{"item":19,"name":20,"@type":21,"position":22},"https://docshare.wps.com","Home","ListItem",1,{"item":24,"name":25,"@type":21,"position":26},"https://docshare.wps.com/document/","Document",2,{"item":28,"name":29,"@type":21,"position":30},"https://docshare.wps.com/document/technology/","Technology",3,{"item":32,"name":10,"@type":21,"position":33},"https://docshare.wps.com/document/how-to-design-a-good-api-and-why-it-matters/673532/",4,{"url":32,"name":10,"@type":35,"image":36,"author":41,"headline":10,"publisher":44,"fileFormat":47,"inLanguage":8,"description":12,"dateModified":48,"datePublished":49,"encodingFormat":47,"isAccessibleForFree":50,"interactionStatistic":51},"DigitalDocument",{"url":37,"@type":38,"width":39,"height":40},"https://docshare.wps.com/thumbnails/how-to-design-a-good-api-and-why-it-matters/673532.png","ImageObject",300,407,{"name":42,"@type":43},"Margaret","Person",{"url":19,"name":45,"@type":46},"DocShare","Organization","application/pdf","2026-11-04","2026-11-02",true,{"@type":52,"interactionType":53,"userInteractionCount":55},"InteractionCounter",{"@type":54},"ViewAction",5,{"@type":57,"mainEntity":58},"FAQPage",[59,65,69],{"name":60,"@type":61,"acceptedAnswer":62},"Why is API design important for a company?","Question",{"text":63,"@type":64},"APIs can become major assets that customers invest in, learn, and reuse. Conversely, bad public APIs create a constant stream of support and are hard to fix later.","Answer",{"name":66,"@type":61,"acceptedAnswer":67},"What characteristics define a good API?",{"text":68,"@type":64},"A good API is easy to learn and use, hard to misuse, and supports clear reading and maintenance. It is sufficiently powerful, easy to extend, and appropriate for its intended audience.",{"name":70,"@type":61,"acceptedAnswer":71},"How should requirements and specifications be handled in API design?",{"text":72,"@type":64},"Extract true requirements in the form of use-cases, and be skeptical of proposed solutions. Start with a short specification (about one page), bounce it off stakeholders, then flesh it out as confidence grows through coding.","https://schema.org",{"og:url":32,"og:type":75,"og:title":10,"og:site_name":45,"og:description":12},"article",{"robots":77,"canonical":32},"index,follow",{"doc_id":79,"site_id":7},673532,1793647803,{"code":4,"msg":82,"data":83},"success",[84,88,92,96,100,104,109,114,119,122,126],{"id":22,"doc_module":4,"doc_module_name":25,"category_name":85,"show_sort_weight":86,"slug":87},"Story & Novel",90,"story-novel",{"id":26,"doc_module":4,"doc_module_name":25,"category_name":89,"show_sort_weight":90,"slug":91},"Literature",80,"literature",{"id":33,"doc_module":4,"doc_module_name":25,"category_name":93,"show_sort_weight":94,"slug":95},"Exam",70,"exam",{"id":55,"doc_module":4,"doc_module_name":25,"category_name":97,"show_sort_weight":98,"slug":99},"Comic",60,"comic",{"id":101,"doc_module":4,"doc_module_name":25,"category_name":29,"show_sort_weight":102,"slug":103},6,50,"technology",{"id":105,"doc_module":4,"doc_module_name":25,"category_name":106,"show_sort_weight":107,"slug":108},7,"Healthcare",40,"healthcare",{"id":110,"doc_module":4,"doc_module_name":25,"category_name":111,"show_sort_weight":112,"slug":113},8,"Research & Report",30,"research-report",{"id":115,"doc_module":4,"doc_module_name":25,"category_name":116,"show_sort_weight":117,"slug":118},9,"Religion & Spirituality",20,"religion-spirituality",{"id":117,"doc_module":4,"doc_module_name":25,"category_name":120,"show_sort_weight":117,"slug":121},"World Cup","world-cup",{"id":123,"doc_module":4,"doc_module_name":25,"category_name":124,"show_sort_weight":123,"slug":125},10,"Lifestyle","lifestyle",{"id":127,"doc_module":4,"doc_module_name":25,"category_name":128,"show_sort_weight":55,"slug":129},19,"General","general",{"code":4,"msg":82,"data":131},{"doc_id":79,"user_id":132,"nickname":42,"user_avatar":133,"doc_module":4,"category_id":101,"category_name":29,"doc_title":10,"doc_description":12,"doc_content":134,"file_id":135,"file_url":136,"file_type":137,"file_size":138,"view_count":55,"is_deleted":4,"is_public":22,"is_downloadable":22,"audit_status":22,"page_count":139,"language":140,"language_code":8,"site_id":7,"html_lang":8,"table_of_contents":141,"faqs":142,"seo_title":143,"seo_description":12,"update_tm":80,"read_time":144},137451207643,"https://ap-avatar.wpscdn.com/davatar_3d24733baf745e90a7e4bdd5f77d97b2","How to Design a Good API and Why it Matters  \nJoshua Bloch  \nPrincipal Software Engineer  \n1   How to Design a Good API and Why it Matters  \nWhy is API Design Important?  \n• APIs can be among a company's greatest assets   Customers invest heavily: buying, writing, learning   Cost to stop using an API can be prohibitive   Successful public APIs capture customers  \n• Can also be among company's greatest liabilities   Bad APIs result in unending stream of support calls  \n• Public APIs are forever-one chance to get it right  \n2   How to Design a Good API and Why it Matters  \nWhy is API Design Important to You?  \n• If you program, you are an API designer   Good code is modular–each module has an API  \n• Useful modules tend to get reused  \n  Once module has users, can’t change API at will   Good reusable modules are corporate assets  \n• Thinking in terms of APIs improves code quality  \n3   How to Design a Good API and Why it Matters  \nCharacteristics of a Good API  \n• Easy to learn  \n• Easy to use, even without documentation  \n• Hard to misuse  \n• Easy to read and maintain code that uses it  \n• Sufficiently powerful to satisfy requirements  \n• Easy to extend  \n• Appropriate to audience  \n4   How to Design a Good API and Why it Matters  \nOutline  \nI. The Process of API Design  \nII. General Principles  \nIII. Class Design  \nIV. Method Design  \nV. Exception Design  \nVI. Refactoring API Designs  \n5   How to Design a Good API and Why it Matters  \nI. The Process of API Design  \n6   How to Design a Good API and Why it Matters  \nGather Requirements–with a Healthy Degree of Skepticism  \n• Often you'll get proposed solutions instead   Better solutions may exist  \n• Your job is to extract true requirements   Should take the form of use-cases  \n• Can be easier and more rewarding to build something more general  \n Good  \n7   How to Design a Good API and Why it Matters  \nStart with Short Spec–1 Page is Ideal  \n• At this stage, agility trumps completeness  \n• Bounce spec off as many people as possible   Listen to their input and take it seriously  \n• If you keep the spec short, it’s easy to modify  \n• Flesh it out as you gain confidence   This necessarily involves coding  \n8   How to Design a Good API and Why it Matters  \nWrite to Your API Early and Often  \n• Start before you've implemented the API   Saves you doing implementation you'll throw away  \n• Start before you've even specified it properly   Saves you from writing specs you'll throw away  \n• Continue writing to API as you flesh it out   Prevents nasty surprises  \n  Code lives on as examples, unit tests  \n9   How to Design a Good API and Why it Matters  \nWriting to SPI is Even More Important  \n• Service Provider Interface (SPI)  \n  Plug-in interface enabling multiple implementations   Example: Java Cryptography Extension (JCE)  \n• Write multiple plug-ins before release   If you write one, it probably won't support another   If you write two, it will support more with difficulty   If you write three, it will work fine  \n• Will Tracz calls this “The Rule of Threes”(Confessions of a Used Program Salesman , Addison-Wesley, 1995)  \n Bad  \n10   How to Design a Good API and Why it Matters","cbCaiqA0FGEag00G","https://ap.wps.com/l/cbCaiqA0FGEag00G","pdf",579852,49,"English","# Why is API Design Important?\n# Why is API Design Important to You?\n# Characteristics of a Good API\n# Outline\n## The Process of API Design\n## General Principles","[{\"question\":\"Why is API design important for a company?\",\"answer\":\"APIs can become major assets that customers invest in, learn, and reuse. Conversely, bad public APIs create a constant stream of support and are hard to fix later.\"},{\"question\":\"What characteristics define a good API?\",\"answer\":\"A good API is easy to learn and use, hard to misuse, and supports clear reading and maintenance. It is sufficiently powerful, easy to extend, and appropriate for its intended audience.\"},{\"question\":\"How should requirements and specifications be handled in API design?\",\"answer\":\"Extract true requirements in the form of use-cases, and be skeptical of proposed solutions. Start with a short specification (about one page), bounce it off stakeholders, then flesh it out as confidence grows through coding.\"}]","How to Design a Good API and Why it Matters | PDF",123]