The Entry Point [API Platform]
We've now got a fresh installation of the API Platform up and running. As already mentioned, the API Platform is very much a full featured stack, so it stands to reason that out-of-the-box we will have various routes (or endpoints) that we can start playing with.
As also mentioned, whilst the API Platform is a Symfony project, it doesn't use MVC. Instead it makes use of the ADR design pattern. And this may throw you.
Where normally you may head to the src/Controllers
directory, here you'll just find a .gitignore
file.
Ok, not to worry - I'll try the api/config/routes.yaml
file:
#index:
# path: /
# controller: App\Controller\DefaultController::index
Huh. Just a single commented out example entry.
What gives?
Well, regardless of how a project's routing is configured, we can check out the router just like in any other Symfony 4 project. Via the CLI.
But as Docker is involved, this adds a layer of extra complexity to proceedings. Please watch the video for a little more on this, and an alternative you may prefer.
docker-compose exec php php bin/console debug:router
------------------------------- -------- -------- ------ ---------------------------------
Name Method Scheme Host Path
------------------------------- -------- -------- ------ ---------------------------------
api_entrypoint ANY ANY ANY /{index}.{_format}
api_doc ANY ANY ANY /docs.{_format}
api_jsonld_context ANY ANY ANY /contexts/{shortName}.{_format}
api_greetings_get_collection GET ANY ANY /greetings.{_format}
api_greetings_post_collection POST ANY ANY /greetings.{_format}
api_greetings_get_item GET ANY ANY /greetings/{id}.{_format}
api_greetings_delete_item DELETE ANY ANY /greetings/{id}.{_format}
api_greetings_put_item PUT ANY ANY /greetings/{id}.{_format}
_twig_error_test ANY ANY ANY /_error/{code}.{_format}
------------------------------- -------- -------- ------ ---------------------------------
(yes, the double php
is intentional there btw)
Right, so we can see a bunch of routes already exist.
The api_entrypoint
is all about discovering our new API. Whether you are you - the person who just created this brand new API Platform instance, or you're a person from the Internet, accessing this interesting looking system for the first time - you need a way to discover all the available resources this API offers.
The thing is, humans are really just part of the equation. One super nice and not-so-immediately-obvious point is that our new API is auto-discoverable by computers. All this extra data helps consumers of our API better understand just what the heck we are intending to share, and how to find their way around once inside.
Starting with the Entry Point
The Entry Point (api_entrypoint
) is the intended starting point. In our case, and by default, it's the root of our API.
Both {index}
and {_format}
are optional routing placeholders. In other words, if not provided the default route is /
.
Whilst the {index}
placeholder is optional, if you do use it, the value must be index
. In other words, you must use /index.{some_format}
. You cannot use e.g. /whatever.jsonld
.
Out of the box, this means the Entry Point is https://localhost:8443/
.
And given that the available formats are json
, jsonld
, and html
, this means the variations of our entry point are:
https://localhost:8443/
https://localhost:8443/index.json
https://localhost:8443/index.jsonld
https://localhost:8443/index.html
If you put this system out on the web under the URL of https://api.example.com
, then hey, your entry point is https://api.example.com
.
In other words, don't over think it. But if you really do want to know more, read the Hydra spec.
tl;dr - the entrypoint tells API consumers what's available on our API.