{"id":23194,"date":"2014-12-22T12:27:15","date_gmt":"2014-12-22T10:27:15","guid":{"rendered":"https:\/\/mamchenkov.net\/wordpress\/?p=23194"},"modified":"2014-12-22T12:27:15","modified_gmt":"2014-12-22T10:27:15","slug":"http-api-design-guide","status":"publish","type":"post","link":"https:\/\/mamchenkov.net\/wordpress\/2014\/12\/22\/http-api-design-guide\/","title":{"rendered":"HTTP API Design Guide"},"content":{"rendered":"\n

HTTP API Design Guide<\/a><\/p>\n

This guide describes a set of HTTP+JSON API design practices, originally extracted from work on the Heroku Platform API<\/a>.<\/p>\n

This guide informs additions to that API and also guides new internal APIs at Heroku. We hope it\u2019s also of interest to API designers outside of Heroku.<\/p>\n

Our goals here are consistency and focusing on business logic while avoiding design bikeshedding. We\u2019re looking for a good, consistent, well-documented way<\/em> to design APIs, not necessarily the only\/ideal way<\/em>.<\/p>\n

We assume you\u2019re familiar with the basics of HTTP+JSON APIs and won\u2019t cover all of the fundamentals of those in this guide.<\/p><\/blockquote>\n\n","protected":false},"excerpt":{"rendered":"\n

HTTP API Design Guide This guide describes a set of HTTP+JSON API design practices, originally extracted from work on the Heroku Platform API. This guide informs additions to that API and also guides new internal APIs at Heroku. We hope it\u2019s also of interest to API designers outside of Heroku. Our goals here are consistency … Continue reading HTTP API Design Guide<\/span><\/a><\/p>\n\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"link","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"HTTP API Design Guide #API #WebDev","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"_links_to":"","_links_to_target":""},"categories":[1,18,62,1334],"tags":[2404,3069,1330],"keyring_services":[],"class_list":["post-23194","post","type-post","status-publish","format-link","hentry","category-general","category-programming","category-technology","category-web-work","tag-api","tag-best-practices","tag-web-development","post_format-post-format-link"],"aioseo_notices":[],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack-related-posts":[{"id":29027,"url":"https:\/\/mamchenkov.net\/wordpress\/2018\/11\/25\/crell-apiproblem-a-simple-implementation-of-the-api-problem-specification\/","url_meta":{"origin":23194,"position":0},"title":"Crell\/ApiProblem – a simple implementation of the api-problem specification","author":"Leonid Mamchenkov","date":"November 25, 2018","format":false,"excerpt":"I've been working with REST\/RESTful APIs for a while now.\u00a0 They are usually a lot better than the SOAP or XML-RPC stuff we had before.\u00a0 But they are also not perfect.\u00a0 Error handling and reporting is a common area between many implementations that needs more attention and consistency.\u00a0 Turns out,\u2026","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":28861,"url":"https:\/\/mamchenkov.net\/wordpress\/2018\/10\/15\/documenting-lists-with-swagger\/","url_meta":{"origin":23194,"position":1},"title":"Documenting lists with Swagger","author":"Leonid Mamchenkov","date":"October 15, 2018","format":false,"excerpt":"Swagger is a great tool for documenting APIs.\u00a0 Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation. We use Swagger a lot at work.\u00a0 We've even pushed the bar\u2026","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"https:\/\/i0.wp.com\/mamchenkov.net\/wordpress\/wp-content\/uploads\/2018\/10\/swagger-500x345.png?resize=350%2C200&ssl=1","width":350,"height":200},"classes":[]},{"id":28333,"url":"https:\/\/mamchenkov.net\/wordpress\/2018\/01\/16\/json-server\/","url_meta":{"origin":23194,"position":2},"title":"JSON Server","author":"Leonid Mamchenkov","date":"January 16, 2018","format":false,"excerpt":"JSON Server is a handy tool for anybody working with or developing the REST\/JSON APIs.\u00a0 It's a ready-made \"fake\" API server, that is super easy to setup with your end points and your data.\u00a0 And the best part - it's not just read-only.\u00a0 You can work with POST, PUT, PATCH,\u2026","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":27806,"url":"https:\/\/mamchenkov.net\/wordpress\/2017\/07\/27\/public-json-apis\/","url_meta":{"origin":23194,"position":3},"title":"Public JSON APIs","author":"Leonid Mamchenkov","date":"July 27, 2017","format":false,"excerpt":"Public APIs is a\u00a0collective list of free JSON APIs for use in web development. \u00a0You can find there web services for all kind of data - anything from weather and currency exchange, through government database, to random snippets like GIF images, Lorem Ipsum text, and quotes.","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":27805,"url":"https:\/\/mamchenkov.net\/wordpress\/2017\/07\/27\/rest-apis-are-rest-in-peace-apis-long-live-graphql\/","url_meta":{"origin":23194,"position":4},"title":"Rest APIs are REST-in-Peace APIs. Long Live GraphQL.","author":"Leonid Mamchenkov","date":"July 27, 2017","format":false,"excerpt":"\"Rest APIs are REST-in-Peace APIs. Long Live GraphQL.\" is yet another look at REST vs. GraphQL for the API implementation. I'm involved with developing quite a bit of REST APIs at work, but for now we are just trying to buy us some time. \u00a0I want to take a really\u2026","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":27145,"url":"https:\/\/mamchenkov.net\/wordpress\/2016\/12\/16\/json-api-no-hal\/","url_meta":{"origin":23194,"position":5},"title":"JSON API? No … HAL!","author":"Leonid Mamchenkov","date":"December 16, 2016","format":false,"excerpt":"Wait, what? \u00a0That's exactly what I said when I read this blog post. \u00a0I am still making my way through the JSON API specification. \u00a0And now it seems I might be wasting my time, as I should be learning HAL. Whereas JSON API is almost like an \u201cORM over HTTP\u201d,\u2026","rel":"","context":"In "All"","block_context":{"text":"All","link":"https:\/\/mamchenkov.net\/wordpress\/category\/general\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]}],"jetpack_sharing_enabled":true,"amp_enabled":true,"_links":{"self":[{"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/posts\/23194","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/comments?post=23194"}],"version-history":[{"count":0,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/posts\/23194\/revisions"}],"wp:attachment":[{"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/media?parent=23194"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/categories?post=23194"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/tags?post=23194"},{"taxonomy":"keyring_services","embeddable":true,"href":"https:\/\/mamchenkov.net\/wordpress\/wp-json\/wp\/v2\/keyring_services?post=23194"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}