What do people think of the proposed API?

[jdormit]

The public API is proposed in the "Usage" section of the README. I'd like to start a discussion about what the final API should look like before I get too far into implementing it. Please comment below!

[judahnator]

At a glance, I am not a huge fan of passing arrays of options into functions. I would rather a stronger typed system with concrete options to pass, either as paramaters or a dedicated object.

Instead of this:

    $actorArray = array(
        'id' => 'https://mysite.com/my_actor',
        'type' => 'Person',
        'preferredUsername' => 'myActor',
    );
    $actor = $activitypub->createActor( $actorArray );

I would rather see this (pseudocode):

    $actor = $activitypub->createActor(string $id, string $type, string $preferredUsername);

Or if the number of options are many and individual options would be a pain, perhaps setters and accessors might be a good way to go.

    $actor = $activitypub->createActor()
        ->setId($id)
        ->setType($type)
        ->setPreferredUsername($preferredUsername);

[jdormit]

I hear that. It would be a lot of work to create a full type system for ActivityStreams objects (see https://www.w3.org/TR/activitystreams-vocabulary/), so it might make sense to pass around arrays at first so I can something useful shipped and then build in a strong type system afterwards. I really like the idea of fluent API/builder pattern type thing.https://github.com/landrok/ActivityPub seems to implement a full type system but none of the protocol yet, so there could be a fruitful collaboration there in the future.

[jdormit]

@judahnator Circling back here, although I think a builder API for ActivityPub objects is still a post-release project, I did change the ActivityPub class constructor to take a type-safe config class rather than an array:

https://github.com/pterotype-project/activitypub-php/blob/master/src/Config/ActivityPubConfigBuilder.php

I think the API for AP objects will be similar, except that the build() methods for those objects will return arrays to maintain compatibility with the existing API and with potential other libraries.

[squeevee]

I like the API. It suits my application very well