🏗 Request builder for Item Properties Setup

[OndraM]

This is finally the first part of the facade layer, which will be used by the end application.

(Names of the builder methods may change later - any suggestions?).

Example usage for this builder and builder factory (this is from the end application point of view):

$matej = new Matej('foo', 'apikey');

$response = $matej->request() // this actually returns the builder factory (method is not yet implemented)
    ->itemPropertiesSetup() // this is method of the builder factory, which returns the concrete builder
    ->addProperties([ItemPropertySetup::timestamp('valid_from'), ItemPropertySetup::string('title')]) // example of add multiple commands at once
    ->addProperty(ItemPropertySetup::timestamp('valid_to')) // add just one command
    ->requestWillDelete() // when this method is added, the requets will actually drop the item properties passed via addProperty(ies) method from the database
    ->send();

Thoughts, comments? PR with builder for Event endpoint will follow soon.

[jirinovak]

itemPropertiesSetupBuilder?

[OndraM]

Its already inside a BuilderFactory, so this would be imho not necessary "noise" in the method naming...

Also we're trying to make the builder API as much readable as possible, so not naming the class names in a full name (but using "natural language" aliases) is kind of the goal.

Does it make sense :-)?

[foglcz]

I like it, although I'm iffy about the requestWillDelete() call. The developer intent is to either create/update, or delete item properties in Matej. I'm curious whether we can make this more obvious.

Two approaches come to mind. One would be to use different factory function:

// Create or update properties:
$response = $matej->request() 
    ->createOrUpdateItemProperties() // creates ItemPropertiesSetupRequestBuilder with "POST" flag
    // ...
    ->send();

// Delete properties:
$response = $matej->request() 
    ->deleteItemProperties() // creates ItemPropertiesSetupRequestBuilder with "DELETE" flag
    // ...
    ->send();

Second approach could be changing the final send() to indicate REST-ness of the API:

$matej = new Matej('foo', 'apikey');

// Create or update item properties:
$response = $matej->request() 
    ->itemPropertiesSetup() 
    // ...
    ->post();

// Delete properties
$response = $matej->request() 
    ->itemPropertiesSetup() 
    // ...
    ->delete();

The beauty of that would be, that in future we could easily expose any PUT or GET functions of the api, by simply calling ->get() or ->put() at the end of the request build.
However, we would have to check for invalid state - so that dev cannot execute a GET request against POST only endpoint. While neat, I'm not sure if there are any GET or PUT endpoints in the pipeline - I'm not aware that there are.

Yay or nay?

[foglcz]

Add - third option - rename $matej->request():

$matej = new Matej('foo', 'apikey');

// Create or update item properties:
$response = $matej->post() 
    ->itemPropertiesSetup() 
    // ...
    ->send();

// Delete properties
$response = $matej->delete() 
    ->itemPropertiesSetup() 
    // ...
    ->send();

I'm not sure how these affect readability of other calls.

[foglcz]

How would you feel about if (!$this->requestManager instanceof RequestManager) ?

[OndraM]

I don't feel much difference here. Maybe prefer this version a little bit, as I read it like "there is no requeste manager", while the instanceof version is more like "request manager is request manager".

What about you :)? Any advantage for the instanceof version?

[OndraM]

@foglcz Great ideas, thanks! I agree with the point, and I like the custom factory approach the most. I will update the PR soon :).

(BTW there is no update for ItemPropertiesSetup endpoint - once created, the properties (= "columns" in Matej database) cannot be altered. To change their data type you must first delete and then recreate them.)

So maybe this methods of the factory builder?

• setupItemProperties()
• deleteItemProperties()

[OndraM]

Ok, PR updated, how do everyone like the API now? cc @jirinovak @foglcz etc.

$matej = new Matej('foo', 'apikey');

// Create new:
$response = $matej->request()
    ->setupItemProperties()
    ->addProperty(ItemPropertySetup::timestamp('valid_to'))
    ->addProperty(ItemPropertySetup::string('title'))
    ->send();

// Delete:
$response = $matej->request()
    ->deleteItemProperties()
    ->addProperty(ItemPropertySetup::timestamp('valid_to'))
    ->addProperty(ItemPropertySetup::string('title'))
    ->send();

[foglcz]

Nice one! :)