Contexts API

[blizzz]

contributes to #311

Implementation state

• Contexts index
• Context detail
• Context create
• Context update
• Add a node to a Context
• Remove a node from a Context
• Update a node's order on a page
• Transfer ownership
• No endpoint for dedicated page logic so far, as in this iteration we only have one page ("startpage") and as long we manage it automatically with context / node updates.

Examples

Index

Get an overview of available contexts for the current user

Request

curl --silent \
    -H "OCS-APIRequest: true" \
    -u alice:password \
    'https://my.nxt.cld/ocs/v2.php/apps/tables/api/2/contexts?format=json' | jq

Result

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": [
      {
        "id": 0,
        "name": "Test One",
        "iconName": "account_circle",
        "description": "A good context",
        "owner": "foobar",
        "ownerType": 0
      },
      {
        "id": 3,
        "name": "All good things are three",
        "iconName": "local_shipping",
        "description": "A fascinating context",
        "owner": "alice",
        "ownerType": 0
      }
    ]
  }
}

The context with ID 0 stems for a share towards requesting user alice (either direct or group share), while the context with ID 3 is owned by them.

ownerType is always 0 (= user) in the first Contexts iteration.

Get full context information for a context receiver (by share)

Show Context

Request

curl --silent \
    -H "OCS-APIRequest: true" \
    -u jenna:jenna 
    'https://my.nxt.cld/ocs/v2.php/apps/tables/api/2/contexts/11?format=json' | jq

Result

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "id": 11,
      "name": "Vacation requests",
      "iconName": "holiday_village",
      "description": "Applications for vacations",
      "owner": "0",
      "ownerType": null,
      "sharing": {
        "5": {
          "share_id": 5,
          "receiver": "jenna",
          "receiver_type": "user",
          "display_mode_default": 0,
          "display_mode": 2
        }
      },
      "nodes": {
        "2": {
          "id": 2,
          "node_id": 9,
          "node_type": "table",
          "permissions": 660
        },
        "5": {
          "id": 5,
          "node_id": 19,
          "node_type": "view",
          "permissions": 660
        },
        "4": {
          "id": 4,
          "node_id": 17,
          "node_type": "view",
          "permissions": 660
        },
        "3": {
          "id": 3,
          "node_id": 13,
          "node_type": "view",
          "permissions": 660
        },
        "1": {
          "id": 1,
          "node_id": 7,
          "node_type": "table",
          "permissions": 660
        }
      },
      "pages": {
        "1": {
          "content": {
            "2": {
              "order": 20,
              "node_rel_id": 2
            },
            "5": {
              "order": 30,
              "node_rel_id": 5
            },
            "4": {
              "order": 50,
              "node_rel_id": 4
            },
            "3": {
              "order": 60,
              "node_rel_id": 3
            },
            "1": {
              "order": 90,
              "node_rel_id": 1
            }
          },
          "id": 1,
          "page_type": "startpage"
        }
      }
    }
  }
}

Create Context

Creating a context

The nodes are optional. The context is created empty without nodes, when those are not provided.

Request

curl --silent \
    -X POST \
    -u alice:password \
    -H "OCS-APIRequest: true" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Enchanting Pancake", "iconName": "airline_seat_recline_extra", "description": "comparison of pancake receipes, ingredients, cafés and cooks.", "nodes": [{"id": 4, "type": "0", "permissions": 7}, {"id": 2, "type": "1", "permissions": 4}] }' \
    'https://my.nc.srv/ocs/v2.php/apps/tables/api/2/contexts?format=json' | jq

Return

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "id": 20,
      "name": "Enchanting Pancake",
      "iconName": "airline_seat_recline_extra",
      "description": "comparison of pancake receipes, ingredients, cafés and cooks.",
      "owner": "alice",
      "ownerType": 0,
      "sharing": null,
      "nodes": [
        {
          "id": 36,
          "contextId": 20,
          "nodeId": 4,
          "nodeType": "table",
          "permissions": 7
        },
        {
          "id": 37,
          "contextId": 20,
          "nodeId": 2,
          "nodeType": "views",
          "permissions": 4
        }
      ],
      "pages": {
        "id": 10,
        "contextId": 20,
        "pageType": "startpage",
        "content": {
          "10": {
            "id": 10,
            "nodeRelId": 36,
            "order": 10
          },
          "11": {
            "id": 11,
            "nodeRelId": 37,
            "order": 20
          }
        }
      }
    }
  }
}

Update Context

Updating a context

This does not include transfering a context. The basic information name iconName and description can be changed. When their values are not provided, they are being left unchanged.

Request

curl --silent \
    -X PUT \
    -u alice:password \
    -H "OCS-APIRequest: true" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Enchanting Guitar", "iconName": "view_headline" "description": "A wonderful serenity has taken possession of my entire soul, like these sweet mornings of spring which I enjoy with my whole heart. I am alone, and feel the charm of existence in this spot, which was created for the bliss of souls like mine.", "nodes": [{"id": 4, "type": "0", "permissions": 7, "order": 100}, {"id": 7, "type": "1", "permissions": 4, "order": 60}] }' \
    'https://my.nc.srv/master/ocs/v2.php/apps/tables/api/2/contexts/26?format=json' | jq

Return

The full Context object is being returned.

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "id": 26,
      "name": "Enchanting Guitar",
      "iconName": "view_headline",
      "description": "A wonderful serenity has taken possession of my entire soul, like these sweet mornings of spring which I enjoy with my whole heart. I am alone, and feel the charm of existence in this spot, which was created for the bliss of souls like mine.",
      "owner": "alice",
      "ownerType": 0,
      "sharing": [],
      "nodes": {
        "64": {
          "id": 64,
          "node_id": 4,
          "node_type": "0",
          "permissions": 7
        },
        "65": {
          "id": 63,
          "node_id": 7,
          "node_type": "1",
          "permissions": 4
        },
      },
      "pages": {
        "13": {
          "content": {
            "19": {
              "order": 100,
              "node_rel_id": 64
            },
            "20": {
              "order": 60,
              "node_rel_id": 65
            },
          },
          "id": 13,
          "page_type": "startpage"
        }
      }
    }
  }
}

Delete a specific node from a Context

Deleting a node from a context

The node is being automatically removed from any page content. The whole Context object is returned upon success.

Request

curl --silent \
    -X POST \
    -u alice:password \
    -H "OCS-APIRequest: true" \
    -H "Content-Type: application/json" \
    -d '{ "nodeId": 4, "nodeType": 0, "permissions": 7 }' \
    'https://my.nc.srv/ocs/v2.php/apps/tables/api/2/contexts/26/nodes?format=json' | jq

Return

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "id": 26,
      "name": "Enchanting Pancake",
      "iconName": "airline_seat_recline_extra",
      "description": "comparison of pancake receipes, ingredients, cafés and cooks.",
      "owner": "alice",
      "ownerType": 0,
      "sharing": [],
      "nodes": {
        "63": {
          "id": 63,
          "node_id": 2,
          "node_type": "1",
          "permissions": 4
        }
      },
      "pages": {
        "13": {
          "content": {
            "18": {
              "order": 20,
              "node_rel_id": 63
            }
          },
          "id": 13,
          "page_type": "startpage"
        }
      }
    }
  }
}

Change order of contents in a page

Change the order of the page

In this example, the order of three content items is changed. One does not exists. Those are being ignored. However returned are only the content items that actually where updated.

Request

curl --silent \
    -X PUT \
    -u alice:password \
    -H "OCS-APIRequest: true" \
    -H "Content-Type: application/json" \
    -d '{ "content": [ {"id": 18, "order": 60}, {"id": 19, "order": 161}, { "id": 404, "order": 404} ]}' \
    'https://my.nxt.cld/ocs/v2.php/apps/tables/api/2/contexts/26/pages/13?format=json' | jq

Return

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": [
      {
        "id": 18,
        "pageId": 13,
        "nodeRelId": 63,
        "order": 60
      },
      {
        "id": 19,
        "pageId": 13,
        "nodeRelId": 64,
        "order": 161
      }
    ]
  }
}

Transfer ownership of a Context

Change the owner of the context

At the moment where we only support user owner contexts, the newOwnerType parameter is optional and defaults to 0(user), but might change in future.

The user the context is transferred to must exist.

Request

curl --silent \
    -X PUT \
    -u alice:password \
    -H "OCS-APIRequest: true" \
    -H "Content-Type: application/json" \
    -d '{"newOwnerId": "bob", "newOwnerType": 0}' \
    'https://example.com/ocs/v2.php/apps/tables/api/2/contexts/26/transfer?format=json' | jq

Return

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "id": 26,
      "name": "Enchanting Guitar",
      "iconName": "view_headline",
      "description": "A wonderful serenity has taken possession of my entire soul, like these sweet mornings of spring which I enjoy with my whole heart. I am alone, and feel the charm of existence in this spot, which was created for the bliss of souls like mine.",
      "owner": "bob",
      "ownerType": 0,
      "sharing": [],
      "nodes": {
        "63": {
          "id": 63,
          "node_id": 2,
          "node_type": "1",
          "permissions": 4
        },
        "64": {
          "id": 64,
          "node_id": 4,
          "node_type": "0",
          "permissions": 7
        }
      },
      "pages": {
        "13": {
          "content": {
            "18": {
              "order": 60,
              "node_rel_id": 63
            },
            "19": {
              "order": 161,
              "node_rel_id": 64
            }
          },
          "id": 13,
          "page_type": "startpage"
        }
      }
    }
  }
}

occ Commands

I also added them while doing it

occ tables:contexts:list [options] [--] [<user-id>]

Description:
  Get all contexts or contexts available to a specified user

Usage:
  tables:contexts:list [options] [--] [<user-id>]

Arguments:
  user-id                User ID of the user

occ tables:contexts:show [options] [--] <context-id> [<user-id>]

Description:
  Get all contexts or contexts available to a specified user

Usage:
  tables:contexts:show [options] [--] <context-id> [<user-id>]

Arguments:
  context-id             The ID of the context to show
  user-id                Optionally, showing the context from the perspective of the given user

[blizzz]

I see some Controller names are prefixed with Api. I can adjust to that if this is preferred 🤷

[blizzz]

activity is doing the same 😇

[blizzz]

Added also a GET to fetch the information for a context. While in the overview there are only basic information from the context DB, the endpoint for a specific context is more detailed. It fetches data for sharing, the nodes, and the pages as well. Unfold Get full context information for a context receiver (by share) to get a response preview (ignore the permission value of 660, that's a placeholder for now).

The table/view data has to be fetched separately.

@enjeck What do you think? Did i oversee something, or do you have ideas for improvements?

The second commit is not super clean yet (therefore the temporary commit message), but generally should do what it does. I wonder whether i misuse the Mapper and Entity though, going across the tables. I could split of all the fetching of the sharing, node, and page data, but it would result in more DB queries. And in the end I'd have to compose them altogether in some type as well. Insofar I guess it is ok (unless some future need suggests otherwise - the modification parts are still ahead).

[enjeck]

@enjeck What do you think? Did i oversee something, or do you have ideas for improvements?

I don't understand enough of the code to say much. But if there's a GET request for fetching contexts, I guess we'll have more for creating, editing and deleting?

[blizzz]

@enjeck What do you think? Did i oversee something, or do you have ideas for improvements?

I don't understand enough of the code to say much. But if there's a GET request for fetching contexts, I guess we'll have more for creating, editing and deleting?

Yes, unfold the examples in the PR description ^ There is a usage example with curl as well as result output.

Creating, Editing, Deleting will follow. So far i filled tables with dummy data for my testing.

[blizzz]

Just pushed a quick implementation of creating contexts (no occ yet, curl example added to description).

[blizzz]

Added more endpoints and two examples ^

[blizzz]

Almost complete, not very polished, but the endpoints should be there (just transfer upcoming) – I rushed it a bit now.. Needs better descriptions and I have to make it nice for openapi, but the examples in the description ^ should give a good idea already. Happy about feedback and of course open for improvements.

[blizzz]

Updated Controller information for OpenAPI, but did not regenerated openapi.json, because it needs #919

[juliusknorr]

Nice, I wasn't aware we have this event

[blizzz]

(rebased)