Skip to content

Commit

Permalink
Website and documentation!
Browse files Browse the repository at this point in the history
  • Loading branch information
@JakeWharton
JakeWharton committed May 13, 2013
1 parent 1e15eae commit 84df744
Show file tree
Hide file tree
Showing 13 changed files with 551 additions and 44 deletions.
59 changes: 15 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,62 +3,29 @@ Retrofit

Type-safe REST client for Android and Java by Square, Inc.

For more information please see [the website][1].

Usage
-----

Create an interface for your API. You can create as many of these interfaces as you like. For
each interface you create, calling `RestAdapter.create(MyInterface.class)` will create an
instance of that API handler, which you can then store and use throughout your application. An
example interface:
Download
--------

```java
public interface DummyServiceAsync {
// Produces a url like "foo/bar?id=idValue".
@GET("foo/bar")
void normalGet(@Name("id") String id, Callback<MyJsonObj> callback);
Download [the latest JAR][2] or grab via Maven:

// Produces a url like "foo/idValue/bar?category=categoryValue".
@GET("foo/{id}/bar")
void getWithPathParam(@Name("id") String id, @Name("category") String category, Callback<MyJsonObj> callback);

// Produces a url like "foo/bar/idValue" and body like "id=idValue&body=bodyValue".
@POST("foo/bar/{id}")
void normalPost(@Name("id") String id, @Name("body") String body, Callback<MyJsonObj> callback);

// Produces a url like "foo/bar/idValue" and body generated by MyJsonObj.
@POST("foo/bar/{id}")
void singleEntityPost(@SingleEntity MyJsonObj card, @Name("id") String id, Callback<MyJsonObj> callback);
}
```

Each method has a `Callback` type specified at the end of the parameter list. This is how your
application will handle the results of your network calls asynchronously: errors and successful
responses are both handled by the `Callback` interface.

If you want to use the `@SingleEntity` method of specifying request body (see `singleEntityPost` above),
your `MyJsonObject` will need to implement `TypedBytes`.

For synchronous execution, omit the `Callback` parameter and specify the response as the return type.

```java
public interface DummyServiceSync {
@GET("foo/bar")
MyJsonObj normalGet(@Name("id") String id);
}
```xml
<dependency>
<groupId>com.squareup.retrofit</groupId>
<artifactId>retrofit</artifactId>
<version>(insert latest version)</version>
</dependency>
```

Also worth noting: for POST/PUT requests using default form encoding for the request entity (see
normalPost), any path parameters are also included in the request body. This is different from the
behavior of GET/DELETE, where path parameters are excluded from the query string.




License
=======

Copyright 2012 Square, Inc.
Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand All @@ -71,3 +38,7 @@ License
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


[1]: http://square.github.io/retrofit/
[2]: http://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.squareup.retrofit&a=retrofit&v=LATEST
220 changes: 220 additions & 0 deletions website/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,220 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Retrofit</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A type-safe REST client for Android and Java">
<link href="static/bootstrap-combined.min.css" rel="stylesheet">
<link href="static/app.css" rel="stylesheet">
<link href="static/app-theme.css" rel="stylesheet">
<link href="http://fonts.googleapis.com/css?family=Roboto:400,300italic,100,100italic,300" rel="stylesheet" type="text/css">
<!--[if lt IE 9]><script src="static/html5shiv.min.js"></script><![endif]-->
</head>
<body data-target=".content-nav">
<header>
<div class="container">
<div class="row">
<div class="span5">
<h1>Retrofit</h1>
</div>
<div class="span7">
<menu>
<ul>
<li><a href="#download" class="menu download">Download <span class="version-tag">Latest</span></a></li>
<li><a href="http://github.com/square/retrofit" data-title="View GitHub Project" class="menu github"><img src="static/icon-github.png" alt="GitHub"/></a></li>
<li><a href="http://square.github.io/" data-title="Square Open Source Portal" class="menu square"><img src="static/icon-square.png" alt="Square"/></a></li>
</ul>
</menu>
</div>
</div>
</header>
<section id="subtitle">
<div class="container">
<div class="row">
<div class="span12">
<h2>A type-safe <strong>REST client</strong> for Android and Java</h2>
</div>
</div>
</div>
</section>
<section id="body">
<div class="container">
<div class="row">
<div class="span9">
<h3 id="introduction">Introduction</h3>
<p>Retrofit turns your REST API into a Java interface.</p>
<pre class="prettyprint">public interface GitHubService {
@GET("/users/{user}/repos")
List&lt;Repo> listRepos(@Path("user") String user);
}</pre>
<p>The <code>RestAdapter</code> class generates an implementation of the <code>GitHubService</code> interface.</p>
<pre class="prettyprint">GitHubService service = restAdapter.create(GitHubService.class);</pre>
<p>Each call on the generated <code>GitHubService</code> makes an HTTP request to the remote webserver.</p>
<pre class="prettyprint">service.listRepos("octocat", new Callback&lt;List&lt;Repo>>() {
...
});</pre>
<p>Use annotations to describe the HTTP request:</p>
<ul>
<li>URL paramater replacement and query parameter support</li>
<li>Object conversion to request body (e.g., JSON, protocol buffers)</li>
<li>Multipart request body and file upload</li>
</ul>

<h3 id="api-declaration">API Declaration</h3>
<p>Annotations on the interface methods and its parameters indicate how a request will be handled.</p>

<h4>Request Method</h4>
<p>Every method must have an HTTP annotation that provides the request method and relative URL. There are five built-in annotations: <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, and <code>HEAD</code>. The relative URL of the resource is specified in the annotation.</p>
<pre class="prettyprint">@GET("/users/list")</pre>
<p>You can also specify query parameters in the URL.</p>
<pre class="prettyprint">@GET("/users/list?sort=desc")</pre>
</pre>

<h4>URL Manipulation</h4>
<p>A request URL can be updated dynamically using replacement blocks and parameters on the method. A replacement block is an alphanumeric string surrounded by <code>{</code> and <code>}</code>. A corresponding parameter must be annotated with <code>@Path</code> using the same string.</p>
<pre class="prettyprint">@GET("/group/{id}/users")
List&lt;User> groupList(@Path("id") int groupId);</pre>
<p>Query parameters can also be added.</p>
<pre class="prettyprint">@GET("/group/{id}/users")
List&lt;User> groupList(@Path("id") int groupId, @Query("sort") String sort);</pre>

<h4>Request Body</h4>
<p>An object can be specified for use as an HTTP request body with the <code>@Body</code> annotation.</p>
<pre class="prettyprint">@POST("/users/new")
void createUser(@Body User user, Callback&lt;User> cb);</pre>
<p>The object will also be converted using the <code>RestAdapter</code>'s converter.</p>

<h4>Form Encoded and Multipart</h4>
<p>Methods can also be declared to send form-encoded and multipart data.</p>
<p>Form-encoded data is sent when <code>@FormUrlEncoded</code> is present on the method. Each key-value pair is annotated with <code>@Field</code> containing the name and the object providing the value.</p>
<pre class="prettyprint">@FormUrlEncoded
@POST("/user/edit")
User updateUser(@Field("first_name") String first, @Field("last_name") String last);</pre>
<p>Multipart requests are used when <code>@Multipart</code> is present on the method. Parts are declared using the <code>@Part</code> annotation.</p>
<pre class="prettyprint">@Multipart
@PUT("/user/photo")
User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description);</pre>
<p>Multipart parts use the <code>RestAdapter</code>'s converter or they can implement <code>TypedOutput</code> to handle their own serialization.</p>

<h4>Synchronous vs. Asynchronous</h4>
<p>Methods can be declared for either synchronous or asynchronous execution.</p>
<p>A method with a return type will be executed sychronously.</p>
<pre class="prettyprint">@GET("/user/{id}/photo")
Photo listUsers();</pre>
<p>Asynchronous execution requires the last parameter of the method be a <code>Callback</code>.</p>
<pre class="prettyprint">@GET("/user/{id}/photo")
void listUsers(@Path("id") int id, Callback&lt;Photo> cb);</pre>
<p>On Android, the callbacks will be executed on the main thread. For desktop applications the callbacks will happen on the same thread that executed the HTTP request.</p>

<h4>Response Object Type</h4>
<p>HTTP responses are automatically converted to a specified type using the <code>RestAdapter</code>'s converter which defaults to JSON. The desired type is declared as the method return type or using the <code>Callback</code>.
<pre class="prettyprint">@GET("/users/list")
List&lt;User> userList();

@GET("/users/list")
void userList(Callback&lt;List&lt;User>> cb);</pre>
<p>For access to the raw HTTP response use the <code>Response</code> type.</p>
<pre class="prettyprint">@GET("/users/list")
Response userList();

@GET("/users/list")
void userList(Callback&lt;Response> cb);</pre>

<!--<h3 id="restadapter-configuration">RestAdapter Configuration</h3>
<p><code>RestAdapter</code> is the class through which your API interfaces are turned into callable objects. By default, Retrofit will give you sane defaults for your platform but it allows for customization.</p>
<h4>Converter</h4>
<p>The converter is responsible for serializing and deserializing objects in HTTP. -->

<h3 id="download">Download</h3>
<p><a href="http://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.squareup.retrofit&a=retrofit&v=LATEST" class="dl version-href">&darr; <span class="version-tag">Latest</span> JAR</a></p>
<p>The source code to the Retrofit, its samples, and this website is <a href="http://github.com/square/retrofit">available on GitHub</a>.</p>

<h4>Maven</h4>
<pre class="prettyprint">&lt;dependency>
&lt;groupId>com.squareup.retrofit&lt;/groupId>
&lt;artifactId>retrofit&lt;/artifactId>
&lt;version><em class="version">(insert latest version)</em>&lt;/version>
&lt;/dependency></pre>

<h3 id="contributing">Contributing</h3>
<p>If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.</p>
<p>When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also make sure your code compiles by running <code>mvn clean verify</code>.</p>
<p>Before your code can be accepted into the project you must also sign the <a href="http://squ.re/sign-the-cla">Individual Contributor License Agreement (CLA)</a>.</p>

<h3 id="license">License</h3>
<pre>Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</pre>
</div>
<div class="span3">
<div class="content-nav" data-spy="affix" data-offset-top="80">
<ul class="nav nav-tabs nav-stacked primary">
<li><a href="#introduction">Introduction</a></li>
<li><a href="#api-declaration">API Declaration</a></li>
<!--<li><a href="#restadapter-configuration">RestAdapter Configuration</a></li>-->
<li><a href="#download">Download</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<ul class="nav nav-pills nav-stacked secondary">
<li><a href="https://plus.google.com/communities/109244258569782858265/stream/63e22a6d-b165-489a-92ab-d35f942beb5b">Google+ Community</a></li>
</ul>
</div>
</div>
</div>
<div class="row">
<div class="span12 logo">
<a href="https://squareup.com"><img src="static/logo-square.png" alt="Square, Inc."/></a>
</div>
</div>
</div>
</section>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="static/bootstrap.min.js"></script>
<script src="static/jquery.smooth-scroll.min.js"></script>
<script src="static/jquery-maven-artifact.min.js"></script>
<script src="static/prettify.js"></script>
<script type="text/javascript">
$(function() {
// Syntax highlight code blocks.
prettyPrint();

// Spy on scroll position for real-time updating of current section.
$('body').scrollspy();

// Use smooth-scroll for internal links.
$('a').smoothScroll();

// Enable tooltips on the header nav image items.
$('.menu').tooltip({
placement: 'bottom',
trigger: 'hover',
container: 'body',
delay: {
show: 500,
hide: 0
}
});

// Look up the latest version of the library.
$.fn.artifactVersion('com.squareup.retrofit', 'retrofit', function(version, url) {
$('.version').text(version);
$('.version-tag').text('v' + version);
$('.version-href').attr('href', url);
});
});
</script>
</body>
</html>
51 changes: 51 additions & 0 deletions website/static/app-theme.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
/* http://www.colorhexa.com/48b982 */

/*** Primary ***/

header,
#subtitle,
a.dl {
background-color: #48b983;
}

.content-nav li.active a,
.content-nav li.active a:hover {
border-left-color: #48b983;
}

/*** One step left on the monochromatic scale ***/

header menu li a:hover,
a.dl:hover {
background-color: #40a776;
}
a {
color: #40a776;
}

/*** Three steps left on the monochromatic scale ***/

a:hover {
color: #32835c;
}


/****************************************************************\
**** Syntax highlighting styles ********************************
\****************************************************************/

.pln { color: #000; }
.str { color: #32835b; }
.kwd { color: #666; }
.com { color: #800; }
.typ { color: #222; }
.lit { color: #666; }
.pun { color: #888; }
.opn { color: #888; }
.clo { color: #888; }
.tag { color: #32835b; }
.atn { color: #606; }
.atv { color: #080; }
.dec { color: #606; }
.var { color: #606; }
.fun { color: #f00; }
Loading

0 comments on commit 84df744

Please sign in to comment.