diff --git a/src/reference/css/manual-singlepage.css b/src/reference/css/manual-singlepage.css new file mode 100644 index 000000000..c43915c31 --- /dev/null +++ b/src/reference/css/manual-singlepage.css @@ -0,0 +1,13 @@ +@IMPORT url("manual.css"); + +body { + background: url("../images/background.png") no-repeat center top; +} + +span.property { + font-family: monospace; +} + +div.command-synopsis { + font-family: monospace; +} \ No newline at end of file diff --git a/src/reference/docbook/index.xml b/src/reference/docbook/index.xml index e6e1da941..8db9786d3 100644 --- a/src/reference/docbook/index.xml +++ b/src/reference/docbook/index.xml @@ -1,12 +1,9 @@ + xsi:schemaLocation="http://docbook.org/ns/docbook http://www.oasis-open.org/docbook/xml/5.0/xsd/docbook.xsd"> Spring Data REST Reference Documentation @@ -34,20 +31,18 @@ - Copies of this document may be made for your own use and for - distribution to others, provided that you do not charge any fee for such - copies and further provided that each copy contains this Copyright - Notice, whether distributed in print or electronically. + Copies of this document may be made for your own use and for distribution to others, provided that you do + not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether + distributed in print or electronically. - + - - Spring Data REST Introduction + - - + + \ No newline at end of file diff --git a/src/reference/docbook/intro.xml b/src/reference/docbook/intro.xml index 709a7357b..a391410aa 100644 --- a/src/reference/docbook/intro.xml +++ b/src/reference/docbook/intro.xml @@ -1,16 +1,804 @@ + xsi:schemaLocation="http://docbook.org/ns/docbook http://www.oasis-open.org/docbook/xml/5.0/xsd/docbook.xsd + http://www.w3.org/1999/xlink http://www.oasis-open.org/docbook/xml/5.0/xsd/xlink.xsd"> - Spring Data REST Introduction + Introduction -
- Overview of Spring Data REST features + Spring Data REST makes exporting domain objects to RESTful clients using + HATEOAS + + principles very easy. It exposes the CRUD methods of the Spring Data + + CrudRepository + + interface to HTTP. Spring Data REST also reads the body of HTTP requests and interprets them as domain objects. It + recognizes relationships between entities and represents that relationship in the form of aLink. + - +
+ HTTP Verb to CRUD Method Mapping + + Spring Data REST translates HTTP calls to method calls by mapping the HTTP verbs to CRUD methods. The + following table illustrates the way in which an HTTP verb is mapped to a + CrudRepository + method. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HTTP verb to CRUD method mapping
VerbMethod
+ GET + + CrudRepository<ID,T>.findOne(ID id) +
+ POST + + CrudRepository<ID,T>.save(T entity) +
+ PUT + + CrudRepository<ID,T>.save(T entity) +
+ DELETE + + CrudRepository<ID,T>.delete(ID id) +
+ + By default, all of these methods are exported to clients. By placing an annotation on your + CrudRepository + subinterface, however, you can turn access to a method off. This is discussed in more detail in the section on + configuration. + +
+ +
+ Resource Discoverability + + A core principle of HATEOAS is that resources should be discoverable through the publication of links that + point to the available resources. There are a number of ways to accomplish this but no real standard way. Spring + Data REST uses a link method that is consistent across Spring Data REST: it provides links in a property called + links. That property is an array of objects that take the form of something resembling an + atom:link + element in the + Atom XML namespace. + + + Resource discovery starts at the top level of the application. By issuing a request to the root URL under + which the Spring Data REST application is deployed, the client can extract a set of links from the returned JSON + object that represent the next level of resources that are available to the client. + + + For example, to discover what resources are available at the root of the application, issue an HTTP GET to + the root URL: + + + + + The + links + property of the result document contains an array of objects that have + rel + and + href + properties on them. + + +
+ Compact vs. Verbose + + When issuing a request to a resource, the default behavior is to provide as much information as possible in + the body of the response. In the case of accessing a + Repository + resource, Spring Data REST will inline entities into the body of the response. This could lead to poor network + performance in the case of a very large number of entities. To reduce the amount of data sent back in the + response, a user agent can request the special content type + application/x-spring-data-compact+json + by placing this in the request + Accept + header. Rather than inlining the entities, this content-type provides a link to each entity in the + links + property. + + + +
+ +
+ +
+ Using the + <command>rest-shell</command> + + + The + + rest-shell + + is a command-line shell that aims to make writing REST-based applications easier. It is based on spring-shell and + integrated with Spring HATEOAS in such a way that REST resources that output JSON compliant with Spring HATEOAS + can be discovered by the shell and interactions with the REST resources become much easier than by manipulating + the URLs in bash using a tool like + curl. + + + The rest-shell provides a number of useful commands for discovering and interacting with REST resources. For + example discover will discover what resources are available and print out an easily-readable table of rels and + URIs that relate to those resources. Once these resources have been discovered, the rel of those URIs can be used + in place of the URI itself in most operations, thus cutting down on the amount of typing needed to issue HTTP + requests to your REST resources. + + +
+ Installing the + <command>rest-shell</command> + + + If you're using Mac OS X and Homebrew, then installation is super easy: + + + + Other platforms are simple as well: just download the archive from the GitHub page and unzip it to a + location on your local hard drive. + +
+ +
+ Discovering resources + + The rest-shell is aimed at making it easier to interact with REST resources by managing the session baseUri + much like a directory in a filesystem. Whenever resources are discovered, you can then follow to a new baseUri, + which means you can then use relative URIs. Here's an example of discovering resources, then following a link by + referencing its rel value, and then using a relative URI to access resources under that new baseUri: + + + discover +rel href +======================================================== +address http://localhost:8080/address +family http://localhost:8080/family +people http://localhost:8080/person +profile http://localhost:8080/profile + +http://localhost:8080:> follow people +http://localhost:8080/person:> list +rel href +=================================================== +people.Person http://localhost:8080/person/1 +people.Person http://localhost:8080/person/2 +people.search http://localhost:8080/person/search + +http://localhost:8080/person:> get 1 +> GET http://localhost:8080/person/1 + +< 200 OK +< ETag: "2" +< Content-Type: application/json +< +{ + "links" : [ { + "rel" : "self", + "href" : "http://localhost:8080/person/1" + }, { + "rel" : "peeps.Person.profiles", + "href" : "http://localhost:8080/person/1/profiles" + }, { + "rel" : "peeps.Person.addresses", + "href" : "http://localhost:8080/person/1/addresses" + } ], + "name" : "John Doe" +}]]> + + + NOTE: If you want tab completion of discovered rels, just use the --rel flag. + +
+ +
+ Creating new resources + + The rest-shell can do basic parsing of JSON data within the shell (though there are some limitations due to + the nature of the command line parsing being sensitive to whitespace). This makes it easy to create new + resources + by including JSON data directly in the shell: + + + post --data "{name: 'John Doe'}" +> POST http://localhost:8080/person/ + +< 201 CREATED +< Location: http://localhost:8080/person/8 +< Content-Length: 0 +< + +http://localhost:8080/person:> get 8 +> GET http://localhost:8080/person/8 + +< 200 OK +< ETag: "0" +< Content-Type: application/json +< +{ + "links" : [ { + "rel" : "self", + "href" : "http://localhost:8080/person/8" + }, { + "rel" : "people.Person.addresses", + "href" : "http://localhost:8080/person/8/addresses" + }, { + "rel" : "people.Person.profiles", + "href" : "http://localhost:8080/person/8/profiles" + } ], + "name" : "John Doe" +}]]> + + If your needs of representing JSON get more complicated than what the spring-shell interface can handle, you + can create a directory somewhere with .json files in it, one file per entitiy, and use the --from option to the + post command. This will walk the directory and make a POST request for each .json file found. + + + post --from work/people_to_load +128 items uploaded to the server using POST. +http://localhost:8080/person:>]]> + + You can also reference a specific file rather than an entire directory. + + post --from work/people_to_load/someone.json +1 items uploaded to the server using POST. +http://localhost:8080/person:>]]> + +
+ +
+ Passing query parameters + + If you're calling URLs that require query parameters, you'll need to pass those as a JSON-like fragment in + the --params parameter to the get and list commands. Here's an example of calling a URL that expects parameter + input: + + + get search/byName --params "{name: 'John Doe'}"]]> + +
+ +
+ Outputing results to a file + + It's not always desirable to output the results of an HTTP request to the screen. It's handy for debugging + but + sometimes you want to save the results of a request because they're not easily reproducible or any number of + other + equally valid reasons. All the HTTP commands take an --output parameter that writes the results of an HTTP + operation to the given file. For example, to output the above search to a file: + + + get search/byName --params "{name: 'John Doe'}" --output by_name.txt >> by_name.txt +http://localhost:8080/person:>]]> +
+ +
+ Sending complex JSON + + Because the rest-shell uses the spring-shell underneath, there are limitations on the format of the JSON + data + you can enter directly into the command line. If your JSON is too complex for the simplistic limitations of the + shell --data parameter, you can simply load the JSON from a file or from all the files in a directory. + + + When doing a post or put, you can optionally pass the --from parameter. The value of this parameter should + either be a file or a directory. If the value is a directory, the shell will read each file that ends with .json + and make a POST or PUT with the contents of that file. If the parameter is a file, then the rest-shell will + simpy + load that file and POST/PUT that data in that individual file. + +
+ +
+ Shelling out to bash + + One of the nice things about spring-shell is that you can directly shell out commands to the underlying + terminal shell. This is useful for doing things like load a JSON file in an editor. For instance, assume I have + the Sublime Text 2 command subl in my path. I can then load a JSON file for editing from the rest-shell like + this: + + + ! subl test.json + http://localhost:8080/person:>]]> + + I then edit the file as I wish. When I'm ready to POST that data to the server, I can do so using the --from + parameter: + + + post --from test.json +1 items uploaded to the server using POST. +http://localhost:8080/person:>]]> +
+ + +
+ Setting context variables + + Starting with rest-shell version 1.1, you can also work with context variables during your shell session. + This + is useful for saving settings you might reference often. The rest-shell now integrates Spring Expression + Language + support, so these context variables are usable in expressions within the shell. + + + + var set --name specialUri --value http://longdomainname.com/api +http://localhost:8080/person:> var get --name specialUri +http://longdomainname.com/api +http://localhost:8080/person:> var list +{ + "responseHeaders" : { + ... HTTP headers from last request + }, + "responseBody" : { + ... Body from the last request + }, + "specialUri" : "http://longdomainname.com/api", + "requestUrl" : ... URL from the last request, + "env" : { + ... System properties and environment variables + } +}]]> + + The variables are accessible from SpEL expressions which are valid in a number of different contexts, most + importantly in the path argument to the HTTP and discover commands, and in the data argument to the put and post + commands. + + + Since the rest-shell is aware of environment variables and system properties, you can incorporate external + parameters into your interaction with the shell. For example, to externally define a baseUri, you could set a + system property before invoking the shell. The shell will incorporate anything defined in the JAVA_OPTS + environment variable, so you could parameterize your interaction with a REST service. + + + discover #{env.baseUri} +rel href +================================================================= +... resources for this URL +http://mylongdomain.com/api:>]]> + +
+ +
+ Per-user shell initialization + + The rest-shell supports a "dotrc" type of initialization by reading in all files found in the + $HOME/.rest-shell/ directory and assuming they have shell commands in them. The rest-shell will execute these + commands on startup. This makes it easy to set variables for commonly-used URIs or possibly set a baseUri. + + + ~/.rest-shell/00-vars +echo "discover #{svcuri}" > ~/.rest-shell/01-baseUri + +> rest-shell + +INFO: No resources found... +INFO: Base URI set to 'http://api.myservice.com/v1' + + ___ ___ __ _____ __ _ _ _ _ __ +| _ \ __/' _/_ _/' _/| || | / / | \ \ +| v / _|`._`. | | `._`.| >< | / / / > > +|_|_\___|___/ |_| |___/|_||_| |_/_/ /_/ +1.2.1.RELEASE + +Welcome to the REST shell. For assistance hit TAB or type "help". +http://api.myservice.com/v1:>]]> +
+ +
+ SSL Certificate Validation + + If you generate a self-signed certificate for your server, by default the rest-shell will complain and + refuse + to connect. This is the default behavior of RestTemplate. To turn off certificate and hostname checking, use the + ssl validate --enabled false command. + +
+ +
+ HTTP Basic authentication + + There is also a convenience command for setting an HTTP Basic authentication header. Use auth basic + --username + user --pasword passwd to set a username and password to base64 encode and place into the Authorization header + that + will be part of the current session's headers. + + + You can clear the authentication by using the auth clear command or by removing the Authorization header + using + the headers clear command. + +
+ +
+ Commands + + The rest-shell provides the following commands: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
rest-shell commands
CommandDescription
+ + baseUri + + uri + + + + Set the base URI used for this point forward in the session. Relative URIs will be calculated relative + to this setting. + +
+ + discover + + --rel + rel + + + path + + + + + Find out what resources are available at the given URI. If no URI is given, use the baseUri. + +
+ + follow + + --rel + rel + + + path + + + + + Set the baseUri to the URI assigned to this given rel or path but do not discover resources. + +
+ + list + + --rel + rel + + + path + + + --params + JSON + + + + Find out what resources are available at the given URI. + +
+ + headers set + --name + name + + --value + value + + + + Set an HTTP header for use from this point forward in the session. +
+ + headers clear + + + Clear all HTTP headers set during this session. +
+ + headers list + + + Print out the currently-set HTTP headers for this session. +
+ + history list + + + List the URIs previously set as baseUris during this session. +
+ + history go + + num + + + + Jump to a URI by pulling one from the history. +
+ + var clear + + + Clear this shell's variable context. +
+ + var get + --name + name + + --value + expression + + + + Get a variable from this shell's context by name or evaluate a shell expression. +
+ + var list + + + List variables currently set in this shell's context. +
+ + var set + + + Set a variable in this shell's context. +
+ + up + + + Traverse one level up in the URL hierarchy. +
+ + get + + --rel + rel + + + path + + + --follow true | false + --params + JSON + + --output + filename + + + + HTTP GET from the given path. If + --follow true + is set, then follow any redirects automatically. If + --output filename + is set, output the the response into the given file. + +
+ + post + + + HTTP POST to the given path, passing JSON given in the --data parameter. +
+ + + + + +
+ + + + + +
+ + + + + +
+ + + + + +
+ + + + + +
+ + + + + +
+ + + + get - HTTP GET from the given path. + post - HTTP POST to the given path, passing JSON given in the --data parameter. + put - HTTP PUT to the given path, passing JSON given in the --data parameter. + delete - HTTP DELETE to the given path. + auth basic - Set an HTTP Basic authentication token for use in this session. + auth clear - Clear the Authorization header currently in use. + ssl validate - Disable certificate checking to work with self-signed certificates. + + +
\ No newline at end of file diff --git a/src/reference/docbook/representations.xml b/src/reference/docbook/representations.xml new file mode 100644 index 000000000..18d6c2b28 --- /dev/null +++ b/src/reference/docbook/representations.xml @@ -0,0 +1,32 @@ + + + + Domain Object Representations + +
+ Links as First-Class Objects + + + + +
+ +
+ Object Mapping + + Spring Data REST returns a representation of a domain object that corresponds to the requested + Accept + type specified in the HTTP request. + + Currently, only JSON representations are supported. Other representation types can be supported in the + future by adding an appropriate converter and updating the controller methods with the appropriate + content-type. + + + +
+ + \ No newline at end of file