REST and GraphQL framework to build API-driven projects

https://api-platform.com

by yagodragon • 7 years ago

230 87 7 years ago

api-platform.com

smt882• 7 years ago

It's not immediately obvious from the summary at the top, but this is a PHP library.

moveax• 7 years ago

In detail a collection of symfony Framework components

dopeboy• 7 years ago

(I realize this library is about PHP - read on for a slight tangent in the Django world)

For the Djangonauts in the crowd, has anyone moved from REST to GraphQL in their teams? How's the transition been and what kind of tools did you use?

I'm giving a talk at this year's PyBay and am looking to solicit some stories / experiences.

_AzMoo2• 7 years ago

Yes. The transition has been frustrating. We won't go back because of the benefits inherent in GraphQL's design, but graphene-django has so much boilerplate that a more complex application becomes very convoluted. In my opinion there's a lot of work to be done to get it to a point where it's not a frustrating experience to implement.

dmix2• 7 years ago

You won’t go back because of the gains but would you have done it again from the start? Or is it more of the supporting libraries being the problem.

Even outside of python many people seem to be on the fence when talking about actually implementing it.

creimers• 7 years ago

Similar experience. While the django rest framework is a joy to use, I’m almost inclined to call graphene a headache. Poor docs, lots of spread our third party extensions that really should be in the core... I have even found myself wondering if the stark discrepancy between drf and graphene reflects or hints at a decline of django as a framework.

dalore3• 7 years ago

We have a public DRF api for third parties. But when creating our own, new, client app we found it easier to create a GrahpQL endpoint.

It was good, but comes with a lot of boilerplate. Then there is the learning curve of GrahphQL in the client. Also the bloated client with it's bucket of features (caching, etc).

We just tend to add GraphQL endpoints as we need. Found the best approach was to open the model, put in the GQL optimizer. Then when the client has settled, freeze the models by putting in some `only` settings to limit fields requested.

heyyeah• 7 years ago

Yes, we're using graphene-django for our internal APIs and maintaining/exposing data through REST for public APIs via DRF. My colleague is looking at Ariadne.

RussianCow4• 7 years ago

We just started using it for parts of our frontend API in production. We started with Graphene but it ultimately fell very short of our expectations, so I actually wrote my own GraphQL library from scratch. It's far from spec-compliant, but it supports the bare minimum needed to be able to run queries and mutations, and provides a lot of performance escape hatches that most GraphQL libraries simply don't (like batched resolution for lists of items, as well as a pre-resolver step for big-picture optimizations).

I plan to open source it in the coming weeks. Email me if you're interested and I will reach out when it's on GitHub.

true_religion3• 7 years ago

Is it based on the graphql core next library?

peteforde4• 7 years ago

Serious question: why voluntarily choose PHP for a greenfield project in 2019? Less terrible is not a huge selling feature when most of the good stuff in Laravel is lifted directly from Rails but with none of the developer happiness.

The only argument I can think of is that you already have a team of PHP experts and they don't want to transition to Ruby, Node or Django.

thinkindie• 7 years ago

this comment is so 2005 and it is suggesting you haven't worked with the latest versions of PHP and the ecosystem around it. From a language perspective, PHP is not any worse than Ruby, Python or Javascript. Composer, Symfony and other libraries have improved PHP projects by a lot.

skrebbel2• 7 years ago

PHP is still super quirky and inconsistent though. You can't fix that without breaking backward compatibility.

loxs• 7 years ago

All of the mentioned are incomparably inferior to TypeScript. You have to go to Go, Kotlin, Rust, Swift to actually compare language-wise (to TS) and still won't be able to compare with ability to code the backend and the frontend in the same language.

cutler4• 7 years ago

Not any worse if you don't mind wading through fanfold pages of code containing mostly doc comments, more blank lines than code and pseudo-Java verbosity. No thanks, I'll take Ruby or Python any day of the week.

skrebbel2• 7 years ago

The deployment story. It's like AWS Lambda without all the downsides or any vendor lock in.

EDIT: ok sure, it won't scale as well as Lambda without extra work.

CuriouslyC3• 7 years ago

Lambda barely has any lock in at all. If you build your app using Lambda and RDS you can transition off AWS easily in a weekend.

fouc• 7 years ago

I'm a Rails developer and over the last couple years I've been noticing that Laravel is huge. Laravel & Vue is a very common combination these days. From looking at the example Laravel code, it seems quite nice.

xDest• 7 years ago

Same question: Who would take Ruby or Django for a new project when the language is not even existing in public discussion?

But honestly, the main reason is that you can find PHP developers everywhere and they are cheap. Given that you want to build a project that grows and advances, that is maintainable, for which you require a vast ecosystem to kick-start your ideas and a lot of very good tooling and free sources of knowledge, you won't find a better platform than PHP.

Ok, Perl might be an alternatively hugely developed language but it is really complicated to find new developers for it. In contrast, you will find a lot of developers, testers, sysops that have the knowledge for working and administering the PHP tech stack. Yes, you could use the coolest language but how would you be able to pay super expensive Go/Kotlin/Node developers once your company has left start-up mode and is there really any gain from that? The risk to be betting on a dying horse might be too high or, less dramatic, everyone is just cooking with water.

If you want to earn money from your company and not just sell your expensive personell at some point it makes sense to start easy and advance the people you have. If you are building API based systems you are not locking yourself in a technology anyways. Given how flexible and fast-moving technology is today one could probably also find a good argument that you absolutely should always base your projects on PHP.

dalore3• 7 years ago

Because those stacks (Ruby/Django) come with automatic admin sections that let you build quite a bit quickly.

But now instead of exposing it as html pages, you expose your django/ruby models using an api like graphql or rest. So then you can use all new fancy js frameworks like react or vue.js.

Ruby and Django developers are as around as much as PHP developers.

CuriouslyC3• 7 years ago

My experience with PHP programmers is that while there are a lot more of them, there aren't a lot of good ones. I suppose if you're just making a fairly simple, server rendered CRUD app, that shouldn't be a problem...

peteforde4• 7 years ago

It's honestly really strange that you'd suggest Rails and Django don't exist in the public conversation. Yes, I literally woke up in the middle of the night thinking about this. Rails 6 is on the verge of release and has nearly 4000 contributors. It powers some of the most valuable companies in the world, and is by far the fastest way to get an API/fancy JS combo up and running. According to Github, there are over 1.1 million projects using Rails. Laravel doesn't report usage, but with 500 contributors there's a disparity in the strength of the communities between the two projects.

Anyhow.

One of my favourite things about the Ruby community is that nobody would ever suggest that we're popular because we're cheap. I don't want to work with people that are an easily replaced commodity. Nobody good is cheap.

m4tthumphrey• 7 years ago

Why would you not? It's 2019, not 2005.

GeneralTspoon• 7 years ago

Anecdotally - I find Laravel to be a much more pleasant experience than Rails (from someone who uses both daily, but has been using Laravel for much longer). Can you point out where you think the experience in Rails is better? Maybe I'm missing something...

For a few cases off the top of my head where PHP/Laravel > Ruby/Rails IMO:

- Waaay less magic in Laravel. Controllers are explicitly named, and views are explicitly rendered from methods (Unlike in Rails where everything can be done based on the naming convention of the files).

- Ruby/Rails has too many ways of doing the same thing. Laravel is quite streamlined in that regard. A big part of this is Rails abusing meta-programming IMO (for example, compare ActiveRecord vs. Eloquent).

- I find Laravel's documentation to be top-tier - I rarely have additional questions after reading the relevant sections. And there's official built-in support for a ton of 3rd party services (e.g. Stripe subcriptions).

- Some support for static types in PHP (better than nothing, but nowhere near where I'd like them to be).

- Blade > ERB IMO. Less noise + easier to read. And again, explicit calls to view.render(["var" => $var]) vs. implicit @var insntance variables tacked on to the controller.

Apart from that, PHP is:

- Less prone to memory leaks due to it spinning up a process/thread per request (which can be quite a big advantage - since it means you don't need orchestration overhead for smaller projects).

- Fast enough that performance isn't really a concern (compared to the amount of stories I've heard about migrating away from Rails due to performance problems - I've never heard the same about Laravel).

It feels to me like Rails blazed the trail for developer happiness a few years ago - but these days it seems like a bit of a relic.

no1youknowz• 7 years ago

I build complex apps. I have been using PHP since 2008.

Prior to taking up Laravel and Vue, it was becoming monotonous to build out websites.

However now with Vue taking up the bulk of work and relegating Laravel to effectively an API for:

- authentication and roles.

- database layer for retrieval and submission

- server side validation

- gateway to the message queue

Fact is, there's so little to use PHP for. I have contemplated moving to GoLang (and may do so in the future). But there is a reason why I stay with Laravel. It's just far easier and far quicker for me to code in PHP than using Javascript (node), GoLang and Python. Couple that with using composer which is a decent package manager. I can iterate very very quickly and have reliable robust code.

Of course, you can argue that the same can be achieved with Rails, GoLang, Python, Javascript, etc, etc. That's great, stick with what works for YOU.

I'm simply not going to put any effort in learning Rails or getting better at another language I know.

I'd rather put in more effort to building out more features and grinding out what matters and that's making sure code turns into $$$. Which is something I think we can all agree with. Use the best tool that you can work with that will do the job well.

peteforde4• 7 years ago

It sounds as though we are in violent agreement.

StreamBright2• 7 years ago

Not sure, but also not sure you are suggesting these other solutions. I like to use Java, Rust and Elixir for web. Depending on the performance requirements these are better languages.

joking3• 7 years ago

sometimes developer performance is more important than the server performance. A lot of sites serve less than a page per minute.

cityzen2• 7 years ago

Serious answer: It's none of your business, literally. There are probably more valid reasons to use PHP than invalid reasons you can think of. You sound like the kind of person that spends more time in the tool aisle at the hardware store than in the actual garage getting anything useful done.

elcomet• 7 years ago

PHP with modern frameworks is good. And very easy to deploy.

hippich• 7 years ago

Can't really know their reasons, but for me - it gets the job done. Not everything is 100% success and require scaling, not everything 100% will grow to huge codebase requiring code burecracy. You can do a lot with PHP until you really hit the wall, and if you get there - it is a good problem to have. Learning new languages and frameworks is great, but it is not required to fulfil business needs and if they have PHP experience and PHP does what they need - it means that PHP is probably a good tool for them at that time.

oiwejfoiwjef• 7 years ago

So you were actually impressed with this project, but instead of congratulating the team you decide to rehash old out-dated arguments and try to bash PHP.

Do you realize this sort of thing is no longer a reflection on the language (folks are immune to it). For people who want to hate just to hate, why are you here on HN? Seriously, go find a subreddit to flame on.

peteforde4• 7 years ago

You're reading into what I said in a very negative way, and extracting incorrect signals in the process. I was very clear in saying that if you are a PHP expert, you should definitely continue to develop with PHP.

It should not be negative to ask why someone might choose a PHP framework given so many other options.

I do find it amazing how little credit Rails gets from other framework communities given how many of their features are directly lifted from concepts that Rails originated or popularized. It's possible that Laravel developers don't know migrations came from Rails, for example.

Anyhow, if you're asking about my opinion, personally... don't confuse hate with pity. I've had to make some changes to a Laravel backend for a client project lately, and if you honestly believe that it's nicer to work with than Rails, we have different working definitions of nice.

dabernathy89• 7 years ago

none of the developer happiness

Weird, because thousands of developers are extremely happy building with Laravel.

tannhaeuser2• 7 years ago

Maybe SOAP isn't so bad after all. Like GraphQL, it can aggregate multiple "API" calls (actually service/protocol invocations) into a single, typed payload to the client, also exposes a typed state model (WSDL ports/interfaces), has uniform error messages, takes care of security contexts and transaction boundaries, models asynchronous/message-queue-based invocations in the same modelling universe rather than binding directly to HTTP, etc.

erdii• 7 years ago

I have never used SOAP/WSDL. What was particularly good or bad about them?

Only heard coworkers rant about the XML stuff...

true_religion3• 7 years ago

He thing about soap was that it was not simple. You had a full object model which was separate from your language and used different semantics. Operating it require a library which wasn’t often nice to work with. It’s the same argument against ORMs. If the library is bad, the ORM becomes a worst common demonominator interface.

tannhaeuser2• 7 years ago

What I said: it looks at the whole story, rather than piecemeally stitching together a stack. The downside is that it's maybe overwhelming, especially with multiple competing protocol specs and stacks doing the same thing.

As to XML: IMHO actually XML isn't a good fit for most API payloads. XML comes from markup languages/SGML which model semistructured data as regular content models, rather than co-inductive data structures of programming languages. The thing is, though, that the alternative, JSON, is really too basic (doesn't have schema-based validation, doesn't have date datatypes or enumerations, hell doesn't even have decimal numbers, etc.) Part of the story why JSON is so popular is that it's untyped and you don't have to agree on schemas, typed payloads, etc. upfront, and can just begin coding - but that also means you don't have typing, service contracts, etc. as your apps mature.

marcosdumay• 7 years ago

The best thing that REST still doesn't do well is that you can point your tools at the SOAP discovery address and they will generate all the stubs for you, CORBA style.

Except that, it is mostly like REST. With a very convoluted specification that you can't hope to match on your own code (so, use tools), and tools disagree on the details (so, be careful to avoid the details).

wil421• 7 years ago

WSDLs will tell your tools how to build the SOAP XML for you. It will even give you things like required fields and field lengths. When you need to update something just update the WSDL and regenerate your messages.

I love REST and JSON. The WSDL is one of the only things I like about SOAP. I’ve had issues where people didn’t give me the correct JSON or they update their scheme without notifying everyone and it breaks. You still need to notify people about WSDL changes.

davidjnelson• 7 years ago

It was great because visual studio would auto generate clients based on the schema. Huge time saver, just import the wsdl and call the api.

softwarelimits• 7 years ago

Took a look at this some time ago, a few things you might like to know before diving deeper:

OpenAPI support

Developers seemed to oversee that there is an important spec-first trend with building apis. Currently there is no way to generate code / models from OpenAPI spec, only generates documentation - so the statement about "OpenAPI integration" is only partially true.

Instead you have to fall back to legacy technique of manually coding models - this is bad for teams that adapted OpenAPI as their single source of truth. With this project you will have to maintain php code on api updates and it breaks any established spec-first OpenAPI roundtrip workflow.

Security

Very weak support for expected security out of the box - you need to implement Symfony based security ideas - if you have already done this and know that dark planet, go for it, if you have never seen that before be prepared for lots of awkwardness:

  /**
   * Secured resource.
   *
   * @ApiResource(
   *     attributes={"access_control"="is_granted('ROLE_USER')"},
   *     collectionOperations={
   *         "get",
   *         "post"={"access_control"="is_granted('ROLE_ADMIN')"}
   *     },
   *     itemOperations={
   *         "get"={"access_control"="is_granted('ROLE_USER') and object.owner == user"},
   *         "put"={"access_control"="is_granted('ROLE_USER') and previous_object.owner == user"},
   *     }
   * )
   * @ORM\Entity
   */

Yes, that is a PHP comment - Symfony uses comments for simulation of the non-existing language feature of annotations. Anybody who needs to make money in the Symfony universe follows that awkward and evil cult. Privately you will always hate it, but if all your team says "cool" you just shut up and accept it (and start looking for the next better job).

The whole security story with Symfony seems to be a horrible mess and after-thought, feels incredible tacked-on and will slowly grow into a maintenance nightmare. Badly maintained external libraries. Every software that uses it implements it in a different way.

But: because of large adaption in companies you will still find a solution for everything - be prepared for a long journey. You will end up with your very own solution and never be sure, if it is really secure - why did you want to use open source in the first place - was it for security reasons?

Interesting alternative security implementation: https://medium.com/@ordermind/better-authorization-for-symfo...

Integration

This is just Symfony, so luckily you will find libraries for everything. However, it seems to be somehow detached from the current API product market, so there are some overlapping and not so obvious integration points with tools that help with API management. Note: this is not a complete api platform like the name suggests - many basic features for API management are missing. Developers should stop simulation of "no other software exists" and instead offer nice integration with some of the advanced api management tools.

Nice: GraphQL output only needs import of one library, no additional coding needed.

Support: Better learn french if you are using this to build your company on.

esistgut2• 7 years ago

Yes, that is a PHP comment - Symfony uses comments for simulation of the non-existing language feature of annotations.

There is an RFC[1] for builtin annotation but no one seems to care.

Nice: GraphQL output only needs import of one library, no additional coding needed.

The GraphQL output is forced to a relay compliant format.

[1] https://wiki.php.net/rfc/annotations_v2

cutler4• 7 years ago

PHP is responsible for the commoditisation of developers. PHP salaries and contract rates are 20% less than for Ruby, Python and Node.js here in the UK. The demands of the job are just the same, ie. Laravel = Rails = Django, but companies assume they can get good developers 20% cheaper just because they use PHP. That's gotta be the main reason to stop using and promoting PHP.

joaobeno• 7 years ago

Blaming the language for the market is a mistake... If you stop promoting PHP, more devs will start on other language, and the market will pay lower, since there is more people to pick from with that particular skill...

cutler4• 7 years ago

Hey, I never looked at it this way - seriously. PHP is doing the rest of the programming world a service by absorbing all the low-end jobs.

yodon• 7 years ago

Or use NestJS to do this in the node ecosystem instead of the PHP ecosystem.

esistgut2• 7 years ago

Using nestjs/typeorm/type-graphql for my current project. I have to admit it is quite refreshing after all of the yaml and docblock annotations of the Symfony/Doctrine/APIPlatform ecosystem.

iosonofuturista• 7 years ago

I'm using Nestjs / typeorm for a mobile app backend, and I must say I am enjoying it a lot.

Previously I would use symfony / doctrine, or some other PHP / ORM combo, but the TypeScript environment is much more to my liking.

This will not convince anyone who dislikes node.js, but if anyone here is considering a node.js backend, give Nestjs a try. I did some tests and found it preferable than pure Express, Sails, or Ember.

Edit: I agree with softwarelimits comments. I absolutely hate synfony/doctrine comment annotations. TypeScript decorators are a better solution.

resurge• 7 years ago

This doesn't seem to do as much as API Platform though?

In API Platform you can just define an entity and it will automatically expose CRUD endpoints for that entity [1].

While in NestJS it seems you still need to define each action manually [2].

It's too bad cause I'm really looking for something like API Platform in Typescript.

[1] https://api-platform.com/docs/distribution/#bringing-your-ow...

[2] https://docs.nestjs.com/controllers

conradfr2• 7 years ago

So my company (a Symfony shop) is currently migrating its API to this, despite my recommendation, and the lack of maturity of the project really shows sometimes.

So far it has slowed us down more than speed us up, except maybe right at the beginning, which in my experience is usually the case with these kind of tools.

From what I hear there was problems due excessive db queries for serializing entities and stuff. I do not work on that project though so I don't have more details and take all that with a grain of salt.

mLuby• 7 years ago

Interesting. What would you say the argument or feature was that won people over?

conradfr2• 7 years ago

Quick bootstrapping for auth, routes, serialization etc I guess.

overcast• 7 years ago

This is ALWAYS my problem with frameworks. All of the database voodoo in the background is a hack. If you end up requiring anything outside of simple operations for a small audience, you'll be inevitably tearing it all out from the ground up. I despise poor query performance more than anything.

kdunglas2• 7 years ago

With API Platform you can write your own SQL / Mongo / whatever queries directly if you prefer: https://api-platform.com/docs/core/data-providers/ / https://api-platform.com/docs/core/data-persisters/ You can also customize / replace / adapt the query generated by the ORM: https://api-platform.com/docs/core/extensions/#extensions

joking3• 7 years ago

I would call this YAHCMS (Yet Another Headless CMS). This has a client app however, where in most of the headless cms they give you a client library at most and you can use the framework that you like.

You have several headless cms for almost any language, so you can start with your language and database of choice and move from there.

I particularly settled with this arquitecture: - Postgraphile as an api layer over the postgresql storage - prect client, as I work with old embedded systems and need something very small.

It doesn't have an automated admin as I don't need it, but if needed you could throw an admin built with react-admin or something similar

michelpp• 7 years ago

Postgraphile is fantastic, as is PostgREST and I support them both on Patreon because they have changed my life for the good immensely.

They both delegate the application entirely to Postgres, which can do everything all other GraphQL/REST frameworks can do, with no ORMs, data copying, restarting worker processes, poorly generated SQL, or worse. Both systems can have a dozen workers per gigabyte of RAM, vs a dozen gigabytes of RAM per worker for something like Django.

Postgres can do per-row security, can run functions in Python or Javascript or many other languages, can integrate with FDWs to many external services (like redis or mongo or what have you). Numerous extensions exist to trigger event streams (like to rabbit) work with advanced text analysis and searching, horizontal sharding of many different flavors, the list goes on.

If you have to write an API that's pure logic and no model, then pick your favorite language; I'd probably use either Flask or node. But when does that ever happen? Maybe a small sidecar API on what is generally a large CRUD application with analytics. Everything SQL is perfectly designed to serve. Stitch them together with GraphQL or route the REST off different path prefixes from the frontend ala microservices.

mixmastamyk2• 7 years ago

How does one do migrations and that sort of thing when using these?

RussianCow4• 7 years ago

It's a matter of what you know. You have to be proficient in Postgres and SQL to make good use of systems like PostgREST and Postgraphile, and the learning curve is fairly steep if you're not used to writing raw SQL daily. If your team is all PHP/Python/Ruby/whatever devs, it probably makes sense to write your API layer in that language rather than force everyone to learn an entirely different platform.

Furthermore, SQL is horribly un-composable; the lack of any real kind of metaprogramming means you end up repeating yourself quite a bit, or at the very least creating multiple layers of indirection in the form of views. I also find it much more painful to work with FDWs and all the various Postgres integration extensions to do simple things like queuing or caching, as opposed to just using a library in your language of choice (although, admittedly, that might be due to lack of experience).

At the end of the day, PostgREST and Postgraphile are great for quickly prototyping an API when all you have is the DB, but I would personally never use them on a project of significant size. YMMV, of course.

PS, assuming you are who I think you are: Hi! Hope you're doing well. :)

bmn__• 7 years ago

I'm quite disappointed in the HAL representation, it lacks standard compliant link relations. OPTIONS is not supported. PATCH with application/merge-patch+json is not supported. Range on items is not supported. JSON home document is not supported. Deprecation is either not supported or undocumented. HTTP authentication schemes are either not supported or undocumented. It looks like the authors of this software don't know what they're doing; I could build much richer HAL documents than them. Try with httpie to see what I mean:

http -v https://demo.api-platform.com/books/526eea89-f98c-4dfc-80bb-... Accept:application/hal+json

kdunglas2• 7 years ago

Hi!

* HAL-compliant link relations are included * OPTIONS is not part of the HAL Internet-Draft * JSON Merge Patch isn't part of the HAL I-D, however, it will be supported in the next major release * Pagination is supported: https://demo.api-platform.com/books.jsonhal. Range aren't part of the HAL I-D. * HTTP authentication schemes are documented using OpenAPI. The HAL I-D contains nothings about auth schemes.

The default, and first-class citizen in API Platform is JSON-LD (+ Hydra). But we know what we're doing and the HAL output is compliant with the I-D. Maybe should you read the spec before posting.

REST and GraphQL framework to build API-driven projects

Related Stories