diff --git a/content/advanced/_index.md b/content/advanced/_index.md index 7fd3dff..b4e8c52 100644 --- a/content/advanced/_index.md +++ b/content/advanced/_index.md @@ -5,7 +5,7 @@ title = "Advanced API Design" weight = 10 +++ -### Chapter 2 +### Part 2 # The Seven Pillars of API Design -We Begin Our Journey in Designing Exquisite RESTful APIs. \ No newline at end of file +Stay Tuned as We Begin Our Journey in Designing Exquisite RESTful APIs. \ No newline at end of file diff --git a/content/basics/_index.md b/content/basics/_index.md index f23c3f6..596597f 100644 --- a/content/basics/_index.md +++ b/content/basics/_index.md @@ -5,7 +5,7 @@ title = "The Basics" weight = 5 +++ -### Chapter 1 +### Part 1 # Learn REST API Basics Quickly learn the basics of what REST is and the core concepts behind it. diff --git a/content/basics/restquicktips.md b/content/basics/restquicktips.md index 9cf0391..9bca9dc 100644 --- a/content/basics/restquicktips.md +++ b/content/basics/restquicktips.md @@ -6,8 +6,12 @@ weight: 20 Whether it's technically RESTful or not (according to the six constraints mentioned previously), here are a few recommended REST-like concepts. These six quick tips will result in better, more usable services. ## Use HTTP Methods to Make Requests Mean Something +{{% notice tip "Verb-Free URLs" "exclamation-circle" %}} API consumers are capable of sending GET, POST, PUT, PATCH and DELETE methods (or verbs), which greatly enhance the clarity of a given request. +Therefore, it is recommended that no verbs (action words) appear in the URL. Instead leverage the HTTP Methods to provide the verb. +{{% /notice %}} + Generally, the five primary HTTP methods are used as follows: | Method | Description | @@ -18,10 +22,14 @@ Generally, the five primary HTTP methods are used as follows: | DELETE | Remove/delete a specific resource by an identifier. | | POST | Create a new resource. Also a catch-all verb for operations that don't fit into the other categories. | -__Note__: GET requests MUST not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource identified by the URI MUST not change. +{{% notice warning "Safety" "exclamation-circle" %}} +GET requests MUST not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource identified by the URI MUST not change. +{{% /notice %}} ## Provide Sensible Resource Names +{{% notice tip "Verb-Free URLs" "exclamation-circle" %}} Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does. As humans are involved in understanding an API, this clarity counts. +{{% /notice %}} Appropriate resource names provide context for a service request, increasing understandability of the API. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications. diff --git a/content/resources/_index.md b/content/resources/_index.md index f67956f..c384d60 100644 --- a/content/resources/_index.md +++ b/content/resources/_index.md @@ -2,8 +2,6 @@ title = "Resources" weight = 50 +++ - -# REST API Resources ## Translations * [Russian](http://www.restapitutorial.ru/)