Add subresource docs by soyuka · Pull Request #199 · api-platform/docs

soyuka · 2017-04-28T12:41:40Z

No description provided.

Simperfit · 2017-04-28T12:48:17Z

+}
+```
+
+If the relation you put the subresource on is a `ToMany`, you will retrieve a collection.


If you put the subresource on a relation that is toMany, you will retrieve...

dunglas

I would also write item and resource (without uppercased first letter) for consistency.

dunglas · 2017-05-15T09:37:32Z

+/**
+ * Answer.
+ *
+ * @ORM\Table(name="answer")


This annotation is useless and should be removed.

dunglas · 2017-05-15T09:38:04Z

+class Answer
+{
+    /**
+     * @ORM\Column(name="id", type="integer")


The name attribute is useless and should be removed.

dunglas · 2017-05-15T09:38:15Z

+    private $id;
+
+    /**
+     * @ORM\Column(name="content", type="string", nullable=false)


All attributes are useless and should be removed.

dunglas · 2017-05-15T09:38:34Z

+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * @ORM\Table(name="question")


The @Table annotation is useless and should be removed.

dunglas · 2017-05-15T09:38:40Z

+class Question
+{
+    /**
+     * @ORM\Column(name="id", type="integer")


The name attribute is useless and should be removed.

dunglas · 2017-05-15T09:39:09Z

+
+    /**
+     * @ORM\OneToOne(targetEntity="Answer", inversedBy="question")
+     * @ORM\JoinColumn(name="answer_id", referencedColumnName="id", unique=true)


The name attribute is useless and should be removed.

dunglas · 2017-05-15T09:39:39Z

+    /**
+     * @ORM\OneToOne(targetEntity="Answer", inversedBy="question")
+     * @ORM\JoinColumn(name="answer_id", referencedColumnName="id", unique=true)
+     * @ApiProperty(subresource=true)


I would put this annotation first to increase its visibility.

dunglas · 2017-05-15T09:40:08Z

+    /**
+     * @ORM\OneToOne(targetEntity="Question", mappedBy="answer")
+     */
+    private $question;


Missing getters/setters (or the property must be public). Same for Question.

dunglas · 2017-05-15T09:41:24Z

+}
+```
+
+Note that all we had to do is to set up `@ApiProperty(subresource=true)` on the `Question::answer` relation. Because the `answer` is a `OneToOne` relation, we know that this subresource is an Item. Therefore the response will look like this:


we have to do?
To set up the @ApiProperty(subresource=true) annotation?
Question::$answer property.

dunglas · 2017-05-15T09:42:35Z

+
+You may want custom groups on subresources. Because a subresource is nothing more than a collection operation, you can set `normalization_context` or `denormalization_context` on that operation. To do so, you need to override `collectionOperations`. Base on the above operation, because we retrieve an answer, we need to alter it's configuration:
+
+<configurations>


I don't think that this that this tag is supported.

we' re using it above though.

soyuka · 2017-05-15T09:53:48Z

Thanks for the review @dunglas, still we may need to rethink how subresources are declared (see our recent discussion on the subject with @teohhanhui).

teohhanhui [12:21 PM]
@soyuka I think for the subresource feature, it'd be really nice to have this:
GET /users/2.jsonld
 "@id": "/users/2",
 "posts": "/users/2/posts"
}
This way we can entirely avoid the join.
[12:23]
we do need better annotation / config syntax.. 😄 (edited)
soyuka [2:02 PM]
hmm, would be possible with the current annotation, if you have a subresource on the given property, normalize as a subresource IRI
[2:02]
though, if I still want the joined collection we need something to avoid conflicts
teohhanhui [6:13 PM]
with the current annotation, it's not configurable..
[6:14]
that's why we need to split that up.. haha
[6:15]
subresource=true -> subresourceOperation=true, maybe (edited)
[6:17]
but probably we need some rethinking about this 🙂
[6:21]
PropertyMetadata::hasSubresource is totally misleading to me.. simply because it should not be treated as first-class metadata about a property.. it should belong in the attributes, since it serves as a hint on whether to expose such a subresource
[6:23]
oh, and the semantics is also wrong.. haha.. we're trying to say, "expose a subresource endpoint for this property", not "this property has a subresource" (????)
soyuka [6:44 PM]
I think that having it as a first-class metadata is more user-friendly. expose a subresource endpoint for this property yeah this is correct, let me know if you have better naming ideas I'm all ears 🙂.

bendavies · 2017-07-06T08:58:53Z

this PR needs updating for api-platform/core#1206

soyuka · 2017-07-06T11:31:55Z

Bumped with @ApiSubresource and comments fixing.

teohhanhui · 2017-07-19T07:10:31Z

+}
+```
+
+If you put the subresource on a relation that is `ToMany`, you will retrieve a collection.


`ToMany` -> to-many

teohhanhui · 2017-07-19T07:10:53Z

+}
+```
+
+Note that all we have to do is to set up `@ApiSubresource` annotation on the `Question::answer` property. Because the `answer` is a `OneToOne` relation, we know that this subresource is an Item. Therefore the response will look like this:


OneToOne -> to-one

Item -> item

teohhanhui · 2017-07-19T07:21:52Z

+
+If you put the subresource on a relation that is `ToMany`, you will retrieve a collection.
+
+Last but not least, subresources can be nested so that `/foos/1/bars/1/foobars` will get `foobars` belonging to `bar=1` itself belonging to `foo=1`. To do this, just add as many subresources annotations as you need.


Subresources can be nested, such that /questions/42/answer/comments will get the collection of comments for the answer to question 42.

teohhanhui · 2017-07-19T07:25:15Z

+
+Since ApiPlatform 2.1, you can declare subresources. A "subresource" is a resource exposed under a path with parameters dependent on another resource. It can result in a collection or an item.
+
+For example, let's create two entities (Question, Answer) and set up a subresource so that `/question/42/answer` gives us the answer to the question `42`:


questions/42/answer

the question `42` -> question 42

teohhanhui · 2017-07-19T07:26:13Z

+```json
+{
+  "@context": "/contexts/Answer",
+  "@id": "/answers/1",


/answers/42

teohhanhui · 2017-07-19T07:26:38Z

+  "@id": "/answers/1",
+  "@type": "Answer",
+  "id": 42,
+  "content": "42",


Life, the Universe, and Everything 😛

soyuka · 2017-08-01T08:38:50Z

Bump

teohhanhui · 2017-08-14T12:08:20Z


+## Subresources
+
+Since ApiPlatform 2.1, you can declare subresources. A subresource is a collection or an item that belongs to another resource. The starting point of a resource must be a relation on an existing resource.


The starting point of a subresource ... ?

Simperfit reviewed Apr 28, 2017

View reviewed changes

soyuka force-pushed the subresource-docs branch 5 times, most recently from adb9fb2 to 2930b49 Compare April 28, 2017 14:37

dunglas requested changes May 15, 2017

View reviewed changes

soyuka force-pushed the subresource-docs branch from 2930b49 to a6c027f Compare July 6, 2017 11:31

teohhanhui suggested changes Jul 19, 2017

View reviewed changes

soyuka force-pushed the subresource-docs branch from a6c027f to faca475 Compare August 1, 2017 08:38

teohhanhui reviewed Aug 14, 2017

View reviewed changes

soyuka force-pushed the subresource-docs branch from faca475 to 3389a6c Compare August 14, 2017 13:57

soyuka force-pushed the subresource-docs branch 3 times, most recently from 6e06d5a to 9f5edf7 Compare September 5, 2017 14:53

Add subresource docs

c9e6c5e

soyuka force-pushed the subresource-docs branch from 9f5edf7 to c9e6c5e Compare September 5, 2017 14:54

soyuka merged commit 8fa3904 into api-platform:master Sep 8, 2017


		You may want custom groups on subresources. Because a subresource is nothing more than a collection operation, you can set `normalization_context` or `denormalization_context` on that operation. To do so, you need to override `collectionOperations`. Base on the above operation, because we retrieve an answer, we need to alter it's configuration:

		<configurations>


		If you put the subresource on a relation that is `ToMany`, you will retrieve a collection.

		Last but not least, subresources can be nested so that `/foos/1/bars/1/foobars` will get `foobars` belonging to `bar=1` itself belonging to `foo=1`. To do this, just add as many subresources annotations as you need.


		Since ApiPlatform 2.1, you can declare subresources. A "subresource" is a resource exposed under a path with parameters dependent on another resource. It can result in a collection or an item.

		For example, let's create two entities (Question, Answer) and set up a subresource so that `/question/42/answer` gives us the answer to the question `42`:


		## Subresources

		Since ApiPlatform 2.1, you can declare subresources. A subresource is a collection or an item that belongs to another resource. The starting point of a resource must be a relation on an existing resource.

Conversation

soyuka commented Apr 28, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soyuka commented May 15, 2017

Uh oh!

bendavies commented Jul 6, 2017

Uh oh!

soyuka commented Jul 6, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soyuka commented Aug 1, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants