Object Types /model/object_types
¶
Through this endpoint you will be able to create new object types, modify, enable/disable or remove an object type.
Create an object type¶
Creation of a new object type happens through POST /model/object_types
endpoint.
-
POST
/model/object_types
¶
Example request (create `cats` type):
POST /model/object_types HTTP/1.1
Host: api.example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "object_types",
"attributes": {
"name": "cats",
"singular": "cat",
"description": "This is a cat"
}
}
In its simplest form the only required attributes are:
name
object type in plural form, this is the canonical form for this type that will activate/cats
endpointsingular
singular form for type
Both must be in lowered snake_case format as internal naming convention, see Naming convention, and must contain at least a letter (a-z) to avoid collisions with numeric ids. They also must be unique in your project.
description
is an optional description of your type
Expected response is HTTP/1.1 201 OK
, with application/vnd.api+json
body data representing object type just created.
If the object type already exists or data is not valid (i.e. lacks of required fields or inconsistent input), POST fails and response will be 400 Bad Request - Invalid data
.
Get single object type¶
You can obtain a single type by using GET /model/object_types/{type}
endpoint.
-
GET
/model/object_types/{type}
¶
{type}
can be a numeric id of the object type or itsname
Example request (get object types):
GET /model/object_types/cats HTTP/1.1
Host: api.example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "13",
"type": "object_types",
"attributes": {
"name": "cats",
"singular": "cat",
"is_abstract": false,
"description": "This is a cat",
"associations": null,
"hidden": null,
"enabled": true,
"table": "BEdita/Core.Objects",
"parent_name": "objects"
},
"meta": {
"created": "2017-11-21T13:56:54+00:00",
"modified": "2017-11-21T13:56:54+00:00",
"core_type": false,
"alias": "Cats",
"relations": []
},
"relationships": {
"left_relations": {
"data": [],
"links": {
"related": "http://api.example.com/model/object_types/13/left_relations",
"self": "http://api.example.com/model/object_types/13/relationships/left_relations"
}
},
"right_relations": {
"data": [],
"links": {
"related": "http://api.example.com/model/object_types/13/right_relations",
"self": "http://api.example.com/model/object_types/13/relationships/right_relations"
}
},
"parent": {
"links": {
"related": "http://api.example.com/model/object_types/13/parent",
"self": "http://api.example.com/model/object_types/13/relationships/parent"
}
}
}
},
"links": {
"self": "http://api.example.com/model/object_types/cats",
"home": "http://api.example.com/home"
}
}
Example response shows us some additional interesting fields:
"is_abstract"
tells us if an object type is abstract or concrete; an abstract type can only have concrete subtypes but there can be no object of this type"associations"
: list of internal entities associated with this type likeDateRanges
orStreams
, formatted as JSON array, defaults to null"hidden"
: list of core properties to hide, those properties will be ignored on every request and response for this type, defaults to null"enabled"
: is a simple flag to activate/deactivate an object type in your project; you will not be able to set it tofalse
if objects of this type or sub-types exist"table"
: table class responsible to store your object data, expressed in CakePHP plugin syntax, defaults to"BEdita/Core.Objects"
"parent_name"
: “name” of the parent abstract type, defaults to"objects"
core_type
is a system flag indicating whether this is acore
object type or a user created type on this project
Relationships available are instead:
"left_relations"
and"right_relations"
representing object types with _left_ or _right_ side relations to this type, see Relations /model/relations for an axplanation"parent"
abstract parent type of this one
Object types list¶
To retrieve a list of object types you can simply use GET /model/object_types
and take advantage of common filters like Field filter or Search Query filter
-
GET
/model/object_types
¶
Example request get enabled object types:
GET /model/object_types?filter[enabled]=true HTTP/1.1
Accept: application/vnd.api+json
Response will contain an array of object_types
in typical list format as shown in Response.
Modify an object type¶
You can modify an object type by using PATCH /model/object_types/{type}
endpoint.
-
PATCH
/model/object_types/{type}
¶
{type}
can be a numeric id of the object type or itsname
Example request: modify an object type:
In this example we will simply disable the newly created type and change its description
PATCH /model/object_types/13 HTTP/1.1
Host: api.example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"id": 13,
"type": "object_types",
"attributes": {
"enabled" : false,
"description" : "This was a cat"
}
}
}
Response 200 OK is expected.
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": 13,
"type": "object_types",
"attributes": {
"username": "johndoe",
"name": "Johnny",
"surname": "Doe"
},
"meta": {
...
},
"relationships": {
...
}
},
"links": {
"self": "http://api.example.com/model/object_types/13",
"home": "http://api.example.com/home"
}
}
"meta"
and "relationships"
here omitted for brevity.
Remove an object type¶
You can delete permanently an object type by using DELETE /model/object_types/{type}
endpoint.
This operation cannot be reversed and will not be allowed if:
- one or more objects of this type exist
core_type
attribute flag istrue
- a subtype of this type exits
-
DELETE
/model/object_types/
(type)¶
{type}
can be a numeric id of the object type or itsname
Example request: delete cats:
DELETE /model/object_types/cats HTTP/1.1
Host: api.example.com
Expected HTTP status response is 204 No Content
.
If object type is not found, response will be 404 Not Found
, if delete operation is not allowed a 403 Forbidden
will be sent.
HTTP/1.1 204 No Content