Updated the api-v1 documentation. #102

docs/api-v1.md

@@ -6,18 +6,18 @@
 
 **GET: http://unleash.host.com/features**
 
-This endpoint is the one all clients should use to fetch all available feature-toggles 
-from the unleash-server. The response returns all active-toggles and the active 
-strategy configuration. A feature-toggle will have at-least one strategy. A 
-strategy will have a 'name' and 'parameters'.
+This endpoint is the one all clients should use to fetch all available feature toggles 
+from the _unleash-server_. The response returns all active feature toggles and their 
+current strategy configuration. A feature toggle will have _at least_ one configured strategy. 
+A strategy will have a `name` and `parameters` map.
 
-_Note:_ Clients should perfer the `strategies` property. Legacy props (`strategy` and `parameters`) 
-will be kept until version 2 of the format. 
+> _Note:_ Clients should perfer the `strategies` property. 
+> Legacy properties (`strategy` & `parameters`) will be kept until **version 2** of the format. 
 
-This endpoint should never return anything besides a valid *20X/304-response*. It will also 
+This endpoint should never return anything besides a valid *20X or 304-response*. It will also 
 include a `Etag`-header. The value of this header can be used by clients as the value of 
 the `If-None-Match`-header in the request to prevent a data transfer if the clients already
-has the latest response locally. 
+has the latest response locally.
 
 **Example response:**
 ```json
@@ -66,9 +66,10 @@ has the latest response locally.
 
 **GET: http://unleash.host.com/features/:featureName**
 
-Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to debug the API. 
+Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to 
+debug the API and should not be used by the client implementations.
 
-_Notice_: You will not get a version property when fetching a specific feature toggle by name. 
+> _Notice_: You will not get a version property when fetching a specific feature toggle by name. 
 
 ```json
 {
@@ -106,12 +107,12 @@ _Notice_: You will not get a version property when fetching a specific feature t
 }
 ```
 
-Used by the admin-dashboard to create a new feature toggles. The name has to be unique, 
+Used by the admin-dashboard to create a new feature toggles. The name **must be unique**, 
 otherwise you will get a _403-response_. 
 
 Returns 200-respose if the feature toggle was created successfully. 
 
-### Create a new Feature Toggle
+### Update a Feature Toggle
 
 **PUT: http://unleash.host.com/features/:toggleName**
 
@@ -130,10 +131,62 @@ Returns 200-respose if the feature toggle was created successfully.
 }
 ```
 
-Used by the admin-dashboard to update a feature toggles. The name has to match an existing features toggle. 
+Used by the admin dashboard to update a feature toggles. The name has to match an 
+existing features toggle. 
 
 Returns 200-respose if the feature toggle was updated successfully. 
 
+### Archive a Feature Toggle
+
+**DELETE: http://unleash.host.com/features/:toggleName**
+
+Used to archive a feature toggle. A feature toggle can never be totally be deleted, 
+but can be archived. This is a design decision to make sure that a old feature 
+toggle suddnely reapear by some one else reusing the same name.
+
+## Archive
+
+### Fetch archived toggles
+
+**GET http://unleash.host.com/archive/features**
+
+Used to fetch list of archived feature toggles
+
+**Example response:**
+```json
+{
+ "version": 1,
+ "features": [
+ {
+ "name": "Feature.A",
+ "description": "lorem ipsum",
+ "enabled": false,
+ "strategies": [
+ {
+ "name": "default",
+ "parameters": {}
+ }
+ ],
+ "strategy": "default",
+ "parameters": {}
+ }
+ ]
+}
+```
+
+### Revive feature toggle
+
+**POST http://unleash.host.com//archive/revive**
+
+**Body:**
+ ```json
+{
+ "name": "Feature.A"
+}
+```
+
+Used to revive a feature toggle. 
+
 
 ## Strategies
 
@@ -194,7 +247,16 @@ Used to create a new Strategy. Name must be unique.
 
 **GET: http://unleash.host.com/events**
 
-Used to fetch all changes in the unleash system. 
+Used to fetch all changes in the unleash system.
+
+Event types:
+
+- feature-created
+- feature-updated
+- feature-archived
+- feature-revived
+- strategy-created
+- strategy-deleted
 
 **Response**