diff --git a/apollo-entity/README.md b/apollo-entity/README.md
index 839c604b4..82b6f4163 100644
--- a/apollo-entity/README.md
+++ b/apollo-entity/README.md
@@ -55,7 +55,7 @@ class MyApplication {
 
   static void init(Environment environment) {
     MyApplication app = new MyApplication();
-    EntityMiddleware entity = EntityMiddleware.jackson(OBJECT_MAPPER);
+    EntityMiddleware entity = EntityMiddleware.forJackson(OBJECT_MAPPER);
 
     Route<SyncHandler<Response<ByteString>>> route = Route.with(
         entity.direct(Person.class),
@@ -71,6 +71,10 @@ class MyApplication {
 }
 ```
 
+[`EntityMiddleware`][1] also support custom codecs through the `forCodec(EntityCodec)` static
+constructor. An [`EntityCodec`][2] defines how to read and write entity types from the `ByteString`
+payloads that apollo handle natively.
+
 ## Handler signatures
 
 The [`EntityMiddleware`][1] interface can create middlewares for several types of handler
@@ -127,8 +131,9 @@ rc -> this::handler
 
 ---
 
-See [`EntityTest`][2] for a complete list of route options and tests.
+See [`EntityMiddlewareTest`][3] for a complete list of route options and tests.
 
 [1]: src/main/java/com/spotify/apollo/entity/EntityMiddleware.java
-[2]: src/test/java/com/spotify/apollo/entity/EntityTest.java
+[2]: src/main/java/com/spotify/apollo/entity/EntityCodec.java
+[3]: src/test/java/com/spotify/apollo/entity/EntityMiddlewareTest.java
 [project skeleton]: https://github.com/spotify/apollo/tree/master/apollo-http-service#maven
diff --git a/apollo-entity/src/main/java/com/spotify/apollo/entity/EntityMiddleware.java b/apollo-entity/src/main/java/com/spotify/apollo/entity/EntityMiddleware.java
index 2d4ec87fe..915385974 100644
--- a/apollo-entity/src/main/java/com/spotify/apollo/entity/EntityMiddleware.java
+++ b/apollo-entity/src/main/java/com/spotify/apollo/entity/EntityMiddleware.java
@@ -43,11 +43,11 @@ static EntityMiddleware forCodec(EntityCodec codec, String contentType) {
     return new CodecEntityMiddleware(codec, contentType);
   }
 
-  static EntityMiddleware jackson(ObjectMapper objectMapper) {
+  static EntityMiddleware forJackson(ObjectMapper objectMapper) {
     return new CodecEntityMiddleware(new JacksonEntityCodec(objectMapper));
   }
 
-  static EntityMiddleware jackson(ObjectMapper objectMapper, String contentType) {
+  static EntityMiddleware forJackson(ObjectMapper objectMapper, String contentType) {
     return new CodecEntityMiddleware(new JacksonEntityCodec(objectMapper), contentType);
   }
 
diff --git a/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityCodecsTest.java b/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityCodecsTest.java
index e0a73bd82..6d3193d8f 100644
--- a/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityCodecsTest.java
+++ b/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityCodecsTest.java
@@ -60,7 +60,7 @@ public class EntityCodecsTest {
 
   @Test
   public void testWithCustomJacksonMapper() throws Exception {
-    EntityMiddleware e = EntityMiddleware.jackson(OBJECT_MAPPER);
+    EntityMiddleware e = EntityMiddleware.forJackson(OBJECT_MAPPER);
 
     ServiceHelper service = ServiceHelper.create(entityApp(e), "entity-test");
     service.start();
@@ -75,7 +75,7 @@ public void testWithCustomJacksonMapper() throws Exception {
 
   @Test
   public void testWithCustomContentType() throws Exception {
-    EntityMiddleware e = EntityMiddleware.jackson(
+    EntityMiddleware e = EntityMiddleware.forJackson(
         OBJECT_MAPPER, "application/vnd+spotify.test+json");
 
     ServiceHelper service =ServiceHelper.create(entityApp(e), "entity-test");
diff --git a/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityMiddlewareTest.java b/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityMiddlewareTest.java
index 7f3c293ed..6f7a40323 100644
--- a/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityMiddlewareTest.java
+++ b/apollo-entity/src/test/java/com/spotify/apollo/entity/EntityMiddlewareTest.java
@@ -312,7 +312,7 @@ public void testBadResponseAsync() throws Exception {
    */
   static void init(Environment environment) {
     EntityMiddlewareTest app = new EntityMiddlewareTest();
-    EntityMiddleware e = EntityMiddleware.jackson(OBJECT_MAPPER);
+    EntityMiddleware e = EntityMiddleware.forJackson(OBJECT_MAPPER);
 
     Stream<Route<AsyncHandler<Response<ByteString>>>> syncRoutes = Stream.of(
         Route.with(e.direct(Person.class), "POST", DIRECT, rc -> app::personDirect),