diff --git a/src/reference/docbook/index.xml b/src/reference/docbook/index.xml index 357f56d7f..189e86074 100644 --- a/src/reference/docbook/index.xml +++ b/src/reference/docbook/index.xml @@ -43,7 +43,10 @@ - + + + + \ No newline at end of file diff --git a/src/reference/docbook/install.xml b/src/reference/docbook/install.xml index e111f2690..9aed1896a 100644 --- a/src/reference/docbook/install.xml +++ b/src/reference/docbook/install.xml @@ -7,7 +7,7 @@ Installing Spring Data REST
- Adding Spring Data REST to an existing Spring MVC application + Introduction Spring Data REST is itself a Spring MVC application and is designed in such a way that it should integrate with your existing Spring MVC applications with very little effort. An existing (or future) layer of services can @@ -20,7 +20,171 @@ class (or subclass it and perform any required manual configuration), and map some URLs to be managed by Spring Data REST. +
+
+ Adding Spring Data REST to a Gradle project + + To add Spring Data REST to a Gradle-based project, add the + spring-data-rest-webmvc + artifact to your compile-time dependencies: + + + +
+ +
+ Adding Spring Data REST to a Maven project + + To add Spring Data REST to a Maven-based project, add the + spring-data-rest-webmvc + artifact to your compile-time dependencies: + + + org.springframework.data + spring-data-rest-webmvc + 1.1.0.M1 +]]> + +
+ +
+ Configuring Spring Data REST + + To install Spring Data REST alongside your existing Spring MVC application, you need to include the + appropriate MVC configuration. Spring Data REST configuration is defined in a class called + RepositoryRestMvcConfiguration. You can either import this class into your existing + configuration using an + @Import + annotation or you can subclass it and override any of the + configureXXX + methods to add your own configuration to that of Spring Data REST. + + + In the following example, we'll subclass the standard + RepositoryRestMvcConfiguration + and add some + ResourceMapping + configurations for the + Person + domain object to alter how the JSON will look and how the links to related entities will be handled. + + + + + There are numerous methods on the + RepositoryRestConfiguration + object to allow you to configure various aspects of Spring Data REST. Please read the javadoc for that class to + get detailed descriptions of the various settings you can control. + + +
+ Adding custom converters + + It may be necessary to add a custom converter to Spring Data REST. You might need to turn a query parameter + into a complex object, for instance. In that case, you'll want to override the + configureConversionService + method and add your own converters. To convert a query parameter to a complex object, for instance, you would + want to register a converter for + String[] + to + MyPojo. + + + +
+
+ +
+ Adding Spring Data REST to Spring MVC + + Since Spring Data REST is simply a Spring MVC application, you only need to include the REST configuration + into the configuration for the + DispatcherServlet. If using a Servlet 3.0 + WebApplicationInitializer + (the preferred configuration for Spring Data REST applications), you would add your subclassed configuration + from above into the configuration for the + DispatcherServlet. The following configuration class is from the example project and + includes datasource configuration for three different datastores and domain models, which will all be exported + by Spring Data REST. + + + + + The equivalent of the above in a standard web.xml will also work identically to this configuration if you + are still in a servlet 2.5 environment. + + + When you deploy this application to your servlet container, you should be able to see what + repositories are exported by accessing the root of the application. You can use curl or, more easily, the + rest-shell: + + < | / / / > > +|_|_\___|___/ |_| |___/|_||_| |_/_/ /_/ +1.2.1.RELEASE + +Welcome to the REST shell. For assistance hit TAB or type "help". +http://localhost:8080:> list +rel href +========================================== +people http://localhost:8080/people +profile http://localhost:8080/profile +customer http://localhost:8080/customer +order http://localhost:8080/order +product http://localhost:8080/product +]]> +
\ No newline at end of file diff --git a/src/reference/docbook/intro.xml b/src/reference/docbook/intro.xml index 703718cb5..0d51d1826 100644 --- a/src/reference/docbook/intro.xml +++ b/src/reference/docbook/intro.xml @@ -168,617 +168,4 @@ -
- 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. -
- - 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/paging.xml b/src/reference/docbook/paging.xml new file mode 100644 index 000000000..a6dbe78d7 --- /dev/null +++ b/src/reference/docbook/paging.xml @@ -0,0 +1,114 @@ + + + + Paging and Sorting + +
+ Paging + + Rather than return everything from a large result set, Spring Data REST recognizes some URL parameters that + will + influence the page size and starting page number. To add paging support to your Repositories, you need to extend + the + PagingAndSortingRepository<T,ID> + interface rather than the basic + CrudRepository<T,ID> + interface. This adds methods that accept a + Pageable + to control the number and page of results returned. + + + + + If you extend + PagingAndSortingRepository<T,ID> + and access the list of all entities, you'll get links to the first 20 entities. To set the page size to any other + number, add a limit parameter: + + + + + To get paging in your query methods, you must change the signature of your query methods to accept a + Pageable + as a parameter and return a + Page<T> + rather than a + List<T>. Otherwise, you won't get any paging information in the JSON and + specifying the query parameters that control paging will have no effect. + + + By default, the URL query parameters recognized are + page, to specify page number + limit, to specify how many results to return on a page, and + sort + to specify the query method parameter on which to sort. To change the names of the query parameters, simply call + the appropriate method on + RepositoryRestConfiguration + and give it the text you would like to use for the query parameter. The following, for example, would set the + paging parameter to + p, the limit parameter to + l, and the sort parameter to + q: + + + + + The URL to use these parameters would then be changed to: + + + + +
+ Previous and Next Links + + Each paged response will return links to the previous and next pages of results based on the current page. + If + you are currently at the first page of results, however, no "previous" link will be rendered. The same is true + for + the last page of results: no "next" link will be rendered if you are on the last page of results. The "rel" + value + of the link will end with ".next" for next links and ".prev" for previous links. + + + +
+
+ +
+ Sorting + + Spring Data REST also recognizes sorting parameters that will use the Repository sorting support. + + To have your results sorted on a particular property, add a sort URL parameter with the name of the property + you want to sort the results on. You can control the direction of the sort by specifying a URL parameter composed + of the property name plus + .dir + and setting that value to either + asc + ordesc. The following would use the + findByNameStartsWith + query method defined on the + PersonRepository + for all + Person + entities with names starting with the letter "K" and add sort data that orders the results on the name property in + descending order: + + + + +
+ \ No newline at end of file diff --git a/src/reference/docbook/representations.xml b/src/reference/docbook/representations.xml index 6133a7ade..1b9968bd4 100644 --- a/src/reference/docbook/representations.xml +++ b/src/reference/docbook/representations.xml @@ -1,17 +1,110 @@ + 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"> Domain Object Representations
Links as First-Class Objects - - + Links are an essential part of RESTful resources and allow for easy discoverability of related resources. In + Spring Data REST, a link is represented in JSON as an object with a + rel + and + href + property. These objects will appear in an array under an object's + links + property. These objects are meant to provide a user agent with the URLs necessary to retrieve resources related to + the current resource being accessed. + + When accessing the root of a Spring Data REST application, for example, links are provided to each repository + that is exported. The user agent can then pick the link it is interested in and follow thathref. + Issue a + get + in the + rest-shell + to see an example of links. + + get +> GET http://localhost:8080/ + +< 200 OK +< Content-Type: application/json +< +{ + "links" : [ { + "rel" : "people", + "href" : "http://localhost:8080/people" + }, { + "rel" : "profile", + "href" : "http://localhost:8080/profile" + }, { + "rel" : "customer", + "href" : "http://localhost:8080/customer" + }, { + "rel" : "order", + "href" : "http://localhost:8080/order" + }, { + "rel" : "product", + "href" : "http://localhost:8080/product" + } ], + "content" : [ ] +}]]> + + +
+ Entity Relationships + + If two entities are related to one another through a database-defined relationship, then that relationship + will appear in the JSON as a link. In JPA, one would place a + @ManyToOne, + @OneToOne, or other relationship annotation. If using Spring Data MongoDB, one would place a + @DBRef + annotation on a property to denote its special status as a reference to other entities. In the example project, + the + Person + class has a related set of + Person + entities in the + siblings + property. If you + get + the resource of a + Person + you will see, in the + siblings + property, the link to follow to get the related + Persons. + + get people/1 +> GET http://localhost:8080/people/1 + +< 200 OK +< Content-Type: application/json +< +{ + "firstName" : "Billy Bob", + "surname" : "Thornton", + "links" : [ { + "rel" : "self", + "href" : "http://localhost:8080/people/1" + }, { + "rel" : "people.person.father", + "href" : "http://localhost:8080/people/1/father" + }, { + "rel" : "people.person.siblings", + "href" : "http://localhost:8080/people/1/siblings" + } ] +}]]> + +
@@ -26,8 +119,107 @@ content-type. - + + Sometimes the behavior of the Spring Data REST's ObjectMapper, which has been specially configured to use + intelligent serializers that can turn domain objects into links and back again, may not handle your domain model + correctly. There are so many ways one can structure your data that you may find your own domain model isn't being + translated to JSON correctly. It's also sometimes not practical in these cases to try and support a complex domain + model in a generic way. Sometimes, depending on the complexity, it's not even possible to offer a generic + solution. + + +
+ Adding custom (de)serializers to Jackson's ObjectMapper + + To accommodate the largest percentage of use cases, Spring Data REST tries very hard to render your + object graph correctly. It will try and serialize unmanaged beans as normal POJOs and it will try and create + links to managed beans where that's necessary. But if your domain model doesn't easily lend itself to reading or + writing plain JSON, you may want to configure Jackson's ObjectMapper with your own custom type mappings and + (de)serializers. + + +
+ Abstract class registration + + One key configuration point you might need to hook into is when you're using an abstract class (or an + interface) in your domain model. Jackson won't know by default what implementation to create for an interface. + Take the following example: + + + interfaces; +}]]> + + In a default configuration, Jackson has no idea what class to instantiate when POSTing new data to the + exporter. This is something you'll need to tell Jackson either through an annotation, or, more cleanly, by + registering a type mapping using a + Module. + + + To add your own Jackson configuration to the + ObjectMapper + used by Spring Data REST, override the + configureJacksonObjectMapper + method. That method will be passed an + ObjectMapper + instance that has a special module to handle serializing and deserializing + PersistentEntitys. You can register your own modules as well, like in the following + example. + + + + + Once you have access to the + SetupContext + object in your + Module, you can do all sorts of cool things to + configure Jacskon's JSON mapping. You can read more about how + Modules work on Jackson's wiki: + + http://wiki.fasterxml.com/JacksonFeatureModules + + +
+ +
+ Adding custom serializers for domain types + + If you want to (de)serialize a domain type in a special way, you can register your own implementations + with Jackson's + ObjectMapper + and the Spring Data REST exporter will transparently handle those domain objects correctly. To add + serializers, from your + setupModule + method implementation, do something like the following: + + + +
+
+
\ No newline at end of file diff --git a/src/reference/docbook/rest-shell.xml b/src/reference/docbook/rest-shell.xml new file mode 100644 index 000000000..fd1f3e85a --- /dev/null +++ b/src/reference/docbook/rest-shell.xml @@ -0,0 +1,619 @@ + + + + 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. +
+ + 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/validation.xml b/src/reference/docbook/validation.xml new file mode 100644 index 000000000..d7fdf9f01 --- /dev/null +++ b/src/reference/docbook/validation.xml @@ -0,0 +1,28 @@ + + + + Validation + + Integrating validation into Spring Data REST is as easy as registering your + Validator + implementation with the + ValidatingRepositoryEventListener, whose job it is to trigger + validators whenever certain events happen inside Spring Data REST. + + + To add your validators, override the + configureValidatingRepositoryEventListener + method and call the + addValidator + method: + + + + + \ No newline at end of file