New documentation hierarchy suggestion for Api-Platform 2.x.

API-Platform New Documentation Hierarchy.md

API-Platform Documentation

Getting started

1. Introduction

Introduction, concepts, features, other resources

2. Installation

1. On top of an existing Symfony project
2. As a new project with Symfony Flex
3. The Distribution: Create powerful APIs with ease

3. Mapping the entities

4. A full-working example

Bring your own model, Validating, Admin, React PWA, Debugging

Usage and configuration

1. General design considerations

2. The Schema Generator

Schema.org introduction, (improve SEO, automatic validation, ...), Model scaffolding.

3. Mapping the entities

4. Operations

Operations introduction, enabling/disabling, configuration.

5. Subresources

Path, access control, depth

6. Serialization & Unserialization

Process introduction, Context/Groups/Relations, Groups per operation, Embedding relations

7. The Event system

8. Semantics & Validation with schema.org

9. Configuration reference

Pagination, Filters & Sorting

1. Pagination

Enabling/disabling, itemsPerPage, maximumItemsPerPage, ...

2. Built-in filters

Search, Date, Boolean, ...

3. Ordering

Order filter, set default order

Security

1. JWT authentication

2. FOSUserBundle integration

3. Access control

Access control expressions, configure access control messages

Exposing your API

1. Versioning

2. Deprecating resources or properties

3. The Sunset HTTP header

4. Customize error messsages

5. HTTP2/Push related resources

Consuming your API

1. OpenAPI/Swagger export

2. Client Generator

React, NextJS, Vue, etc

3. AngularJS integration

Fetching and persisting data

1. Built-in Doctrine support

2. MongoDB

3. ElasticSearch

4. Custom implementation

Documenting / Specifying your API

1. Swagger / OpenAPI support

2. JSON Schema support

3. Extending JSON-LD and Hydra Contexts

4. Swagger UI

5. ReDoc UI

6. GraphiQL

7. NelmioApiDocBundle Integration

GraphQL

1. Enabling GraphQL

2. IDEs

3. Queries

4. Mutations

5. Pagination, Filters & Sorting

6. Security

7. Serialization context

Groups, dynamic groups,different types

8. Types

Custom types, modify the extracted types

9. Export Schema in SDL

10. Common issues

Name conversion, nesting operator

Real-time and streaming capabilities

1. Enabling Mercure support

2. Pushing the API updates

3. Dispatching Private Updates (Authorized Mode)

The Admin Component

1. Introduction

2. Getting started

3. Authentication support

4. Handling relations to collections

5. Customize the admin

Testing

1. Creating data fixtures

2. Writing functional tests

3. To go further

ApiTestCase, Behat, ...

Deployment

1. Self-managed

Link to SF docs, refer to Nginx "too big header issue"

2. Kubernetes

3. Heroku

4. Platform.sh

5. Traefik

Caching & Performance optimization

1. Built-in Cache invalidation

2. Custom Cache HTTP Headers

3. Metadata cache

4. Doctrine queries & indexes

5. PHP-PM / Roadrunner

6. Profiling with Blackfire.io

Advanced usage

1. Custom operations / controllers

2. DTOs

3. Custom identifiers

4. Extending built-in Doctrine implementation

Ex. block anonymous users

5. Data providers / Data persisters

6. CQRS & Async message processing (Symfony Messenger)

How do I?

1. Enable MongoDB support

+ create custom ODM extension

2. Enable ElasticSearch support

+ create custom ElasticSearch extension

3. Change the serialization context on a request basis

4. Change the serialization context on a per-item basis

5. Select the properties to serialize

6. Handle file uploads

7. Push real-time updates with Mercure

8. Prefix routes for all operations

9. Enable several formats

10. Use a custom path resolver

11. Accept application/x-www-form-urlencoded form data

12. Extend the JSON-LD context

13. Embed the JSON-LD context

14. Use snake_case instead of camelCase

15. Add extra data during serialization

16. Enable NelmioApiDocBundle integration

Troubleshooting

1. Common Docker issues

2. API-Platform & JMS serializer

3. Nginx "too big header" issue

4. Need help?

Symfony Slack / Stackoverflow

Miscellaneous

1. Release process

2. Contributing

Contribution guides, contribution code of conduct