We use cookies on this site to enhance your user experience. By clicking "OK, I Agree" or using our site, you consent to the use of cookies unless you have disabled them. View our cookie policy to learn more.
OK, I AGREE
TRACK
APIs >
COURSE
API Platform: Serious RESTful APIs
Buy Access to Course

Relations and IRIs

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00
Previous Chapter

Next Chapter
Edit on Github

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

I just tried to create a CheeseListing by setting the owner property to 1: the id of a real user in the database. But... it didn't like it! Why? Because in API Platform and, commonly, in modern API development in general, we do not use ids to refer to resources: we use IRIs. For me, this was strange at first... but I quickly fell in love with this. Why pass around integer ids when URLs are so much more useful?

Check out the response of the user we just created: like every JSON-LD response, it contains an @id property... that isn't an id, it's an IRI! And this is what you'll use whenever you need to refer to this resource.

Head back up to the CheeseListing POST operation and set owner to /api/users/1. Execute that. This time... it works!

And check it out, when it transforms the new CheeseListing into JSON, the owner property is that same IRI. That is why Swagger documents this as a "string"... which isn't totally accurate. Sure, on the surface, owner is a string... and that's what Swagger is showing in the cheeses-Write model.

But we know... with our human brains, that this string is special: it actually represents a "link" to a related resource. And... even though Swagger doesn't quite understand this, check out the JSON-LD documentation: at /api/docs.jsonld. Let's see, search for owner. Ha! This is a bit smarter: JSON-LD knows that this is a Link... with some fancy metadata to basically say that the link is to a User resource.

The big takeaway is this: a relation is just a normal property, except that it's represented in your API with its IRI. Pretty cool.

Adding cheesesListings to User

What about the other side of the relationship? Use the docs to go fetch the CheeseListing with id = 1. Yep, here's all the info, including the owner as an IRI. But what if we want to go the other direction?

Let's refresh to close everything up. Go fetch the User resource with id 1. Pretty boring: email and username. What if you also want to see what cheeses this user has posted?

That's just as easy. Inside User find the $username property, copy the @Groups annotation, then paste above the $cheeseListings property. But... for now, let's only make this readable: just user:read. We're going to talk about how you can modify collection relationships later.

186 lines src/Entity/User.php
... lines 1 - 22
class User implements UserInterface
{
... lines 25 - 58
/**
... line 60
* @Groups("user:read")
*/
private $cheeseListings;
... lines 64 - 184
}

Ok, refresh and open the GET item operation for User. Before even trying this, it's already advertising that it will now return a cheeseListings property, which, interesting, will be an array of strings. Let's see what User id 1 looks like. Execute!

Ah.. it is an array! An array of IRI strings - of course. By default, when you relate two resources, API Platform will output the related resource as an IRI or an array of IRIs, which is beautifully simple. If the API client needs more info, they can make another request to that URL.

Or... if you want to avoid that extra request, you could choose instead to embed the cheese listing data right into the user resource's JSON. Let's chat about that next.

Leave a comment!

  • 2019-12-09 weaverryan

    Hey Ben Bonora!

    Hmm, so it sounds like you have a bit of a messy database structure. I don't mean that to sound bad - you mentioned that you can't change the DB structure - that's a reality that we often need to work in :). In a more perfect world, the "stations" table would have a true relation to the "markets" table through a join table. That would then all be mapped correctly on Doctrine (as a ManyToMany relationship) and API Platform would be happy.

    > I want to be able to get a markets object

    Because you have a Markets entity, this part should already be ok. I'm guessing this is not a problem ;)

    > as well as post/put/patch market values to the stations endpoint.

    This IS a problem... probably. Questions:

    A) For your Station resource, do you want a markets JSON field to be returned? If so, do you want it to be the array of ids? Array of IRIs? Embedded Market objects?

    B) For post/put/patch of the Station resource... if your markets property is an array of ids... then you should be able to simply send an array of ids on the markets property and it will work. There is no referential integrity in the database or anything... but I think it would be that simple. But... I think I may be missing something - let me know if I am ;).

    Cheers!

  • 2019-12-05 Ben Bonora

    I should also include that the returned values from the station.markets column looks something like this...
    {12,14,...}

    I want to be able to get a markets object as well as post/put/patch market values to the stations endpoint.

  • 2019-12-05 Ben Bonora

    I'm using a postgres database and I have a table called `stations` with a column called `markets`. This column type is an array and contains a collection of market ID's. I also have a market table. I've created an entity for the station and market tables. One station can be associated with many markets. How do I create a relationship in the station entity to markets? I'm assuming this can be achieved using some annotation magic but I haven't been able to figure it out. I can't change the structure of the DB as it was created before using the API Platform.

  • 2019-11-05 Annemieke Buijs

    Hi Diego, my feeling was right. I just watched the chapter about subresources. And it is recommended to keep things simple and not use subresources. You can easily do the same with the filter options.

  • 2019-10-30 Diego Aguiar

    Hey Annemieke Buijs

    Could you tell me why this structure is better /api/v1/orders/{order_id}?customer_id={customer_id} than the other one? Other projects could just follow that structure.

    What I know about the first structure is that that's the standard structure of RESTful APIs, that might be the reason of your boss but you may want to ask him, so you know the real reason behind it and act accordingly.

    Cheers!

  • 2019-10-29 Diego Aguiar

    Ah, I get it now and yes, you can add a filter to your User resource based on its CheeseListing field. Try something like this:


    // User.php

    /**
     * @ApiFilter(SearchFilter::class, properties={
     *     "cheeseListing": "exact",
     *     ...
     * })
    */
    class User
  • 2019-10-29 Annemieke Buijs

    Hey Diego, thanks for the reply. 👌
    What I mean is: when you do /api/user/2 the response contains the user data and if you want, all the data of all the related 'cheeselistings'. My question is if i can filter on the cheeselistings while using the /api/user/2 call
    Thanks for your help in advance.

  • 2019-10-29 Diego Aguiar

    Hey Annemieke Buijs

    If you know the CheeseListing id, I think you can just do a get request to "/api/cheeselist/{id}".

    Cheers!

  • 2019-10-27 Annemieke Buijs

    And here is another question from me on a sunday. I hope you don't mind. I'm pretty exited about api platform and can't wait to dazzle people with it.
    Case:
    A user has many cheeselistings.
    Api platform gives me the user with all the data of all the cheelistings
    url : /api/user/2


    "cheeseListings": [
    {
    "@id": "/api/cheeses/9",
    "@type": "cheeses",
    "title": "nice cheddar cheese",
    "price": 1000
    },
    ...
    ]

    But what url can i use to get a specific cheeselist of this user. With a filter? /api/user/2?cheeselist_id =....
    And will i still get all the data of this cheese list?
    Oke, that's all folks! Have a good sunday Cheers !

  • 2019-10-27 Annemieke Buijs

    Hi guys, great work as usual !
    I have a product owner that wants the api to have urls like this:
    /api/v1/user/{cust_id}/orders/{order_id}
    /api/v1/user/{cust_id}/products/{product_id}/specs

    There are relations between all data.

    My gut feeling says it's way better to do it like this:
    /api/v1/orders/{order_id}?customer_id={customer_id}
    /api/v1/products/{product_id}?customer_id={customer_id}

    So the api is useful for many other projects.
    What is your opinion about this? I look forward to your answer.

    Thank you and please keep up the good work !!!

  • 2019-09-09 Diego Aguiar

    Hey Isaac Earl

    Welcome to SymfonyCasts! About your question, you made me dug and looks like it's a topic that have been active for quite long. The latest info I could find is this comment: https://github.com/api-plat...
    Seems like that guy find a solution. Give it a try and let us know if it worked for you

    Cheers!

  • 2019-09-07 Isaac Earl

    I purchased a sub to symfonycasts to learn about api-platform... because we are considering using api-platform for an upcoming project we have. Unforunately we won't be able to use IRIs for relations on this project, so I'm hoping this is configurable so I can use regular plain ids. Is this a configurable option for api-platform yet? I found some issues related to this on github but was confused about whether a solution was ever found. Also I would like a supported solution and not a workaround where I have to do something hacky/fragile.

Edit on Github
Previous Chapter
Next Chapter