Skip to content

Commit 228222a

Browse files
glennblockglennblock
committed
Update readme.md
1 parent 0da73e3 commit 228222a

File tree

1 file changed

+124
-64
lines changed

1 file changed

+124
-64
lines changed

‎readme.md‎

Lines changed: 124 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
# CollectionJson
1+
# CollectionJson.NET
22

33
This library provides support for ASP.NET Web API using the [Collection+JSON] (http://amundsen.com/media-types/collection/) hypermedia mediatype authored by [Mike Amundsen] (http://twitter.com/mamund).
44

55
## Features
66

77
* A set of models for fully representing a Collection+Json document.
8+
* Support for extensions
89
* CollectionJsonFormatter which handles Collection+Json representations.
910
* CollectionJsonController which is a drop-in API controller that is designed to make it easy to support Collection+Json. It wires up the formatter for you / removes a lot of cruft.
1011
* A set of adapter contracts for reading and writing Collection+json documents.
@@ -22,57 +23,140 @@ CollectionJson ships with several nuget packages that are factored for client an
2223
* [WebApiContrib.Formatting.CollectionJson.Server] (https://www.nuget.org/packages/WebApiContrib.Formatting.CollectionJson.Server) - Contains controllers for implementing the CJ protocol in ASP.NET Web API.
2324
* [WebApiContrib.Formatting.CollectionJson] (https://www.nuget.org/packages.WebApiContrib.CollectionJson) - Meta package for backward compatability, pulls in WebApiContrib.Formatting.CollectioJson.Server.
2425

25-
## IReadDocument and Collection
26-
This interfaces corresponds to the message format Collection+Json defines for returning Collection+Json results.
26+
## Returning a read document from a server
27+
To create a new read document instantiate a `Collection` instance. The `CollectionJsonFormatter` will write this out to the CollectionJson format.
2728

2829
```csharp
29-
public interface IReadDocument
30+
var document = new ReadDocumnent();
31+
var collection = new Collection { Version = "1.0", Href = new Uri(_requestUri, "/friends/") };
32+
document.Collection = collection;
33+
34+
collection.Links.Add(new Link { Rel = "Feed", Href = new Uri(_requestUri, "/friends/rss") });
35+
36+
foreach (var friend in friends)
3037
{
31-
Collection Collection { get; }
38+
var item = new Item { Href = new Uri(_requestUri, "/friends/" + friend.Id) };
39+
item.Data.Add(new Data { Name = "full-name", Value = friend.FullName, Prompt = "Full Name" });
40+
item.Data.Add(new Data { Name = "email", Value = friend.Email, Prompt = "Email" });
41+
item.Data.Add(new Data{ Name = "short-name", Value = friend.ShortName, Prompt = "Short Name"});
42+
item.Links.Add(new Link { Rel = "blog", Href = friend.Blog, Prompt = "Blog" });
43+
item.Links.Add(new Link { Rel = "avatar", Href = friend.Avatar, Prompt = "Avatar", Render = "Image" });
44+
collection.Items.Add(item);
3245
}
3346

34-
public class Collection
35-
{
36-
public Collection()
37-
{
38-
Links = new List<Link>();
39-
Items = new List<Item>();
40-
Queries = new List<Query>();
41-
Template = new Template();
42-
}
47+
var query = new Query { Rel = "search", Href = new Uri(_requestUri, "/friends"), Prompt = "Search" };
48+
query.Data.Add(new Data { Name = "name", Prompt="Value to match against the Full Name" });
49+
collection.Queries.Add(query);
4350

44-
public string Version { get; set; }
45-
public Uri Href { get; set; }
46-
public IList<Link> Links { get; private set; }
47-
public IList<Item> Items { get; private set; }
48-
public IList<Query> Queries { get; private set; }
49-
public Template Template { get; private set; }
50-
}
51+
var data = collection.Template.Data;
52+
data.Add(new Data { Name = "name", Prompt = "Full Name" });
53+
data.Add(new Data { Name = "email", Prompt = "Email" });
54+
data.Add(new Data { Name = "blog", Prompt = "Blog" });
55+
data.Add(new Data { Name = "avatar", Prompt = "Avatar" });
5156
```
5257

53-
## IWriteDocument and Template
54-
This interface corresponds to the message format Collection+Json defines for creating / updating items.
58+
## Using extensions
59+
The `Collection`, `Data`, `Item`, `Link` and `Query` classes are all extensible to allow for using CollectionJson extensions. There are two different methods for working with extensions.
5560

61+
### Using dynamic
62+
Extensions can be set by casting to dynamic and setting arbitrary extension properties. Below is an example setting the Model extension.
5663
```csharp
57-
public interface IWriteDocument
58-
{
59-
Template Template { get; }
60-
}
64+
var item = new Item { Href = new Uri(_requestUri, "/friends/" + friend.Id) };
65+
dynamic dItem = item;
66+
item.Model = "friend";
67+
```
6168

62-
public class Template
63-
{
64-
public Template()
65-
{
66-
Data = new List<Data>();
67-
}
69+
### Using SetValue
70+
Extensions can be set by calling the SetValue method.
71+
```csharp
72+
var item = new Item { Href = new Uri(_requestUri, "/friends/" + friend.Id) };
73+
item.SetValue("Model", "friend");
74+
```
6875

69-
public IList<Data> Data { get; set; }
70-
}
76+
### Using GetValue
77+
Extensions can be retrieved by calling the GetValue method
78+
```csharp
79+
var model = item.GetValue<string>("Model");
7180
```
7281

73-
## CollectionJsonController
82+
## API
83+
### IReadDocument / ReadDocument
84+
A CollectionJson server returns an object implementing IReadDocument. The `CollectionJsonFormatter` casts the model to this interface to write out the payload. The concrete ReadDocument class implements this interface.
85+
86+
Member | Description
87+
----------- | -----------------------------------------------------------------------------------------------
88+
Collection | Sets the Collection (`Collection`)
89+
90+
### WriteDocument / IWriteDocument
91+
A CollectionJson server receives an object implementing IWriteDocument. The `CollectionJsonFormatter' casts the model to this interface to read in the template. The concrete WriteDocument class implements this interface.
92+
93+
Member | Description
94+
----------- | -----------------------------------------------------------------------------------------------
95+
Template | Contains the write template sent from the client
96+
97+
### Collection
98+
The collection contains all the details for the CollectionJson document
99+
100+
Member | Description
101+
----------- | -----------------------------------------------------------------------------------------------
102+
Version | Sets the CollectionJson version
103+
Links | Contains the top level links (`Link`) for the collection
104+
Items | Contains the collection of items (`Item`)
105+
Queries | Contains the collection of queries (`Query`)
106+
Template | Contains the write template (`Template`) to be retuned to the client
107+
108+
### Item
109+
CollectionJson documents contain one or more items which are represented with the `Item` class.
110+
111+
Member | Description
112+
----------- | -----------------------------------------------------------------------------------------------
113+
Rel | The link relation
114+
Href | Url for dreferencing the item
115+
Rt | Describes the item
116+
Data | Contains the data elements for the item.
117+
Links | Contains the links for the item
118+
119+
### Link
120+
The Link object is used for embedding links with the document
121+
122+
Member | Description
123+
----------- | -----------------------------------------------------------------------------------------------
124+
Rel | The link relation
125+
Href | Url for dreferencing the link
126+
Prompt | Contains a human readable description for the link
127+
Render | How the link should be rendered, should be "image" or "link"
128+
129+
### Query
130+
Queries are sent to the client which it can use to search against data.
131+
132+
Member | Description
133+
----------- | -----------------------------------------------------------------------------------------------
134+
Rel | The link relation
135+
Href | Url for dreferencing the link
136+
Prompt | Contains a human readable description for the link
137+
Rt | Describes the return value of the query
138+
Data | Contains the data elements which the client will use to perform the query
139+
140+
### Template
141+
Templates are sent to the client to instruct it as to which data elements it should send in order to create or update the collection.
142+
143+
Member | Description
144+
----------- | -----------------------------------------------------------------------------------------------
145+
Data | Contains the data elements for the template
146+
147+
148+
### CollectionJsonController_Of_T
74149
This controller is a drop in component that one can derive from to implement the Collection+Json CRUD protocol. It constrains to strictly returning and accepting the correct message formats based on the spec. It also handles concerns like status codes, auto-generating the location header etc.
75150

151+
Member | Description
152+
----------- | -----------------------------------------------------------------------------------------------
153+
Create | Handles creation of a new item.
154+
Read | Handles reading a single or multiple items
155+
Update | Handles updating an existing itemm.
156+
Delete | Removes an existing item.
157+
158+
Below is a sample controller implementation
159+
76160
```csharp
77161
public class FriendsController : CollectionJsonController<Friend>
78162
{
@@ -126,7 +210,7 @@ public class FriendsController : CollectionJsonController<Friend>
126210

127211
An implementer overrides methods from the base. The controller abstracts away the CJ format, which is handled via a set of adapters.
128212

129-
# ICollectionJsonDocumentReader
213+
### ICollectionJsonDocumentReader
130214

131215
The reader is responsible for taking a Collection+JSON write template and convering it into "some" model. The model can be anything from a primitive like a string to a complex object.
132216

@@ -146,7 +230,7 @@ public class FriendDocumentReader : ICollectionJsonDocumentReader<Friend>
146230
}
147231
```
148232

149-
# ICollectionJsonDocumentWriter
233+
### ICollectionJsonDocumentWriter
150234

151235
The writer is responsible for taking the model and writing it out as Collection+Json Document.
152236

@@ -162,32 +246,8 @@ public class FriendDocumentWriter : ICollectionJsonDocumentWriter<Friend>
162246

163247
public IReadDocument Write(IEnumerable<Friend> friends)
164248
{
165-
var document = new ReadDocument();
166-
var collection = new Collection { Version = "1.0", Href = new Uri(_requestUri, "/friends/") };
167-
document.Collection = collection;
168-
169-
collection.Links.Add(new Link { Rel = "Feed", Href = new Uri(_requestUri, "/friends/rss") });
170-
171-
foreach (var friend in friends)
172-
{
173-
var item = new Item { Href = new Uri(_requestUri, "/friends/" + friend.Id) };
174-
item.Data.Add(new Data { Name = "full-name", Value = friend.FullName, Prompt = "Full Name" });
175-
item.Data.Add(new Data { Name = "email", Value = friend.Email, Prompt = "Email" });
176-
item.Data.Add(new Data{ Name = "short-name", Value = friend.ShortName, Prompt = "Short Name"});
177-
item.Links.Add(new Link { Rel = "blog", Href = friend.Blog, Prompt = "Blog" });
178-
item.Links.Add(new Link { Rel = "avatar", Href = friend.Avatar, Prompt = "Avatar", Render = "Image" });
179-
collection.Items.Add(item);
180-
}
181-
182-
var query = new Query { Rel = "search", Href = new Uri(_requestUri, "/friends"), Prompt = "Search" };
183-
query.Data.Add(new Data { Name = "name", Prompt="Value to match against the Full Name" });
184-
collection.Queries.Add(query);
185-
186-
var data = collection.Template.Data;
187-
data.Add(new Data { Name = "name", Prompt = "Full Name" });
188-
data.Add(new Data { Name = "email", Prompt = "Email" });
189-
data.Add(new Data { Name = "blog", Prompt = "Blog" });
190-
data.Add(new Data { Name = "avatar", Prompt = "Avatar" });
249+
//create the document from the friends collection
250+
var document = ...
191251
return document;
192252
}
193253
}

0 commit comments

Comments
 (0)