Providing a new entity type

The Entity CRUD API allows you to easily create a new entity type. You'll get full Create, Read, Update, Delete and Index (CRUDI) functions, and may define your entity to be fieldable or exportable. For a working example, study the code of the "entity_test.module" included as part of the Entity API package located at [MODULES DIRECTORY]/entity/tests/entity_test.module.

To create a new entity type:

• Depend on the entity module.
• Describe your entity's db table as usual in hook_schema(). Add any columns specific to your entity. For some examples, see node_schema() and user_schema().
• Implement hook_entity_info() for your entity. At a minimum, specify the
  controller class of this API, your db table and your object's primary key
  field. Optionally also set the 'entity class' to Entity, or your extended class.

That's it. You can use the entity_save/delete/create() functions to manage your entity, or if you prefer, you can use the methods of your 'entity class', e.g. $entity->save().

To modify the default save/delete/create behavior, extend the provided controller class and override the methods accordingly. However, if you make use of an entity class you may also directly override the methods provided by your entity class, as the API functions entity_save() and entity_delete() pick that up.

The EntityAPIController automatically provides you with your_entity_type_insert/update/delete/pre_save hooks. If your entity is defined to be fieldable, EntityAPIController invokes the field API attachers for you. You only have to write the API docs yourself. For that you may make use of this API documentation template. Also note that schema fields marked as 'serialized' are automatically unserialized upon loading as well as serialized on saving.

A simple example hook_entity_info() implementation could look like the following:

/**
 * Implements hook_entity_info().
 */
function entity_test_entity_info() {
  return array(
    'entity_test' => array(
      'label' => t('Test Entity'),
      'plural label' => t('Test Entities'),
      'entity class' => 'Entity',
      'controller class' => 'EntityAPIController',
      'base table' => 'entity_test',
      'entity keys' => array(
        'id' => 'id',
      ),
      // Use the default label() and uri() functions
      'label callback' => 'entity_class_label',
      'uri callback' => 'entity_class_uri',
    ),
  );
}

Core defines the functions entity_label() and entity_uri() which return the label and the URI for an arbitrary entity type with the help of information provided in hook_entity_info(). In order to take advantage of this, extend the Entity class, override the defaultLabel() and defaultUri() methods, and specify entity_class_label() and entity_class_uri() callbacks in hook_entity_info().
Then you can use $entity->label() or $entity->uri(), as well as the core API functions. Also, other modules will be able to override your behaviors by altering the hook_entity_info() callbacks, while $entity->label() and $entity->uri() reflect these changes just as entity_label() and entity_uri().

For more examples of modules that implement the Entity API, see the provided testing module "entity_test", Profile2, Field collection, Message, Bean or Subs.

Take a look at model, that provides a code example for entity API similar to the example module.

Use Entity Construction Kit (ECK) to create a new entity type and bundles by UI and export info by features is an easy way as a start point.