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.

Episodes

# Title Duration
1 What will our JSON API actually do? 08:46
2 What needs to be in our Database for our Tests to work? 12:32
3 Cleaning up after each Test Run 02:40
4 Docker makes for Easy Databases 09:01
5 Healthcheck [Raw Symfony 4] 07:53
6 Send in JSON data using POST [Raw Symfony 4] 05:33
7 Keep your data nice and tidy using Symfony's Form [Raw Symfony 4] 10:48
8 Validating incoming JSON [Raw Symfony 4] 08:26
9 Nicer error messages [Raw Symfony 4] 06:23
10 GET'ting data from our Symfony 4 API [Raw Symfony 4] 08:11
11 GET'ting a collection of Albums [Raw Symfony 4] 01:50
12 Update existing Albums with PUT [Raw Symfony 4] 05:00
13 Upsetting Purists with PATCH [Raw Symfony 4] 02:39
14 Hitting DELETE [Raw Symfony 4] 02:11
15 How to open your API to the outside world with CORS [Raw Symfony 4] 07:48
16 Getting Setup with Symfony 4 and FOSRESTBundle [FOSRESTBundle] 09:11
17 Healthcheck [FOSRESTBundle] 06:14
18 Handling POST requests [FOSRESTBundle] 08:31
19 Saving POST data to the database [FOSRESTBundle] 09:44
20 Work with XML, or JSON, or Both [FOSRESTBundle] 04:31
21 Going far, then Too Far with the ViewResponseListener [FOSRESTBundle] 03:19
22 GET'ting data from your Symfony 4 API [FOSRESTBundle] 05:58
23 GET'ting a Collection of data from your Symfony 4 API [FOSRESTBundle] 01:27
24 Updating with PUT [FOSRESTBundle] 02:58
25 Partially Updating with PATCH [FOSRESTBundle] 02:15
26 DELETE'ing Albums [FOSRESTBundle] 01:27
27 Handling Errors [FOSRESTBundle] 08:58
28 Introducing the API Platform [API Platform] 08:19
29 The Entry Point [API Platform] 04:30
30 The Context [API Platform] 05:52
31 Healthcheck - Custom Endpoint [API Platform] 05:17
32 Starting with POST [API Platform] 07:08
33 Creating Entities with the Schema Generator [API Platform] 07:38
34 Defining A Custom POST Route [API Platform] 07:31
35 Finishing POST [API Platform] 06:29
36 GET'ting One Resource [API Platform] 02:50