<commit_before>Creating a REST Service
=======================

In this chapter, we'll create a simple REST service.

Assumptions
-----------

This chapter assumes you have read and followed both the [installation
guide](/intro/installation.md) and the [getting started chapter](/intro/getting-started.md). If you
have not, please do before continuing.

You will need to install and configure the `zfcampus/statuslib-example` module in order to perform
this tutorial. Follow these steps:

### Step 1

Within your application root, execute the following:

```console
$ php composer.phar require "zfcampus/statuslib-example:~1.0-dev"
```

### Step 2

Edit the file `config/application.config.php` and add the `StatusLib` module:

```php
array(
    'modules' => array(
        /* ... */
        'StatusLib',
    ),
    /* ... */
)
```

### Step 3

Create a PHP file `data/statuslib.php` that returns an array:

```php
<?php
return array();
```

Make sure the file is writable by the web server user.

### Step 4

Edit the file `config/autoload/local.php` to add the following configuration:

  ```php
  return array(
      /* ... */
      'statuslib' => array(
          'array_mapper_path' => 'data/statuslib.php',
      ),
  );
  ```

### Step 5

Finally, you will need a valid HTTP basic credentials file, usually titled `htpasswd`. You can
generate one using the standard [htpasswd tool provided by
Apache](http://httpd.apache.org/docs/2.2/programs/htpasswd.html), or use an [online htpasswd
generator](http://www.htaccesstools.com/htpasswd-generator/). Store the `htpasswd` file as
`data/htpasswd` in your application. Make a note of the credentials you use so that you can use them
later.

Once those steps are complete, continue with the tutorial.

Terminology
-----------

Within the Apigility documentation, and, in particular, this chapter, uses the following
terminology:

<dl>
    <dt>Entity</dt>
    <dd>
        An <em>addressable</em> item being returned. Entities are distinguished by a unique
        identifier present in the URI.
    </dd>

    <dt>Collection</dt>
    <dd>
        A addressable <em>set</em> of <em>entities</em>. Typically, all entities contained in the
        collection are of the same type, and share the same base URI as the collection.
    </dd>

    <dt>Resource</dt>
    <dd>
        An object that receives the incoming request data, determines whether a <em>collection</em>
        or <em>entity</em> was identified in the URI, and determines what <em>operation</em> to
        perform.
    </dd>

    <dt>Relational Links</dt>
    <dd>
        A URI to a resource that has the described <em>relation</em>. Relational links allow you to
        describe relations between different entities and collections, as well as directly link to
        them so that the web service client can perform operations on those relations. These are
        also sometimes called <em>hypermedia links</em>.
    </dd>
</dl>

REST services return entities and collections, and provide hypermedia links between related entities
and collections. Resource objects coordinate operations, and return entities and collections.

Create a REST Service
---------------------

In this chapter, we're going to build a sample REST service.

In the sidebar, click the "New Service" button. The REST tab is selected by default; provide the
value "Status" for the "Service name" field and press the "Create service" button.

![REST Services Screen](/asset/apigility-documentation/img/intro-first-rest-service-rest-services.png)<commit_msg>Decrease indentation inside definition list<commit_after>Creating a REST Service
=======================

In this chapter, we'll create a simple REST service.

Assumptions
-----------

This chapter assumes you have read and followed both the [installation
guide](/intro/installation.md) and the [getting started chapter](/intro/getting-started.md). If you
have not, please do before continuing.

You will need to install and configure the `zfcampus/statuslib-example` module in order to perform
this tutorial. Follow these steps:

### Step 1

Within your application root, execute the following:

```console
$ php composer.phar require "zfcampus/statuslib-example:~1.0-dev"
```

### Step 2

Edit the file `config/application.config.php` and add the `StatusLib` module:

```php
array(
    'modules' => array(
        /* ... */
        'StatusLib',
    ),
    /* ... */
)
```

### Step 3

Create a PHP file `data/statuslib.php` that returns an array:

```php
<?php
return array();
```

Make sure the file is writable by the web server user.

### Step 4

Edit the file `config/autoload/local.php` to add the following configuration:

  ```php
  return array(
      /* ... */
      'statuslib' => array(
          'array_mapper_path' => 'data/statuslib.php',
      ),
  );
  ```

### Step 5

Finally, you will need a valid HTTP basic credentials file, usually titled `htpasswd`. You can
generate one using the standard [htpasswd tool provided by
Apache](http://httpd.apache.org/docs/2.2/programs/htpasswd.html), or use an [online htpasswd
generator](http://www.htaccesstools.com/htpasswd-generator/). Store the `htpasswd` file as
`data/htpasswd` in your application. Make a note of the credentials you use so that you can use them
later.

Once those steps are complete, continue with the tutorial.

Terminology
-----------

Within the Apigility documentation, and, in particular, this chapter, uses the following
terminology:

<dl>
<dt>Entity</dt>
<dd>
    An <em>addressable</em> item being returned. Entities are distinguished by a unique
    identifier present in the URI.
</dd>

<dt>Collection</dt>
<dd>
    A addressable <em>set</em> of <em>entities</em>. Typically, all entities contained in the
    collection are of the same type, and share the same base URI as the collection.
</dd>

<dt>Resource</dt>
<dd>
    An object that receives the incoming request data, determines whether a <em>collection</em>
    or <em>entity</em> was identified in the URI, and determines what <em>operation</em> to
    perform.
</dd>

<dt>Relational Links</dt>
<dd>
    A URI to a resource that has the described <em>relation</em>. Relational links allow you to
    describe relations between different entities and collections, as well as directly link to
    them so that the web service client can perform operations on those relations. These are
    also sometimes called <em>hypermedia links</em>.
</dd>
</dl>

REST services return entities and collections, and provide hypermedia links between related entities
and collections. Resource objects coordinate operations, and return entities and collections.

Create a REST Service
---------------------

In this chapter, we're going to build a sample REST service.

In the sidebar, click the "New Service" button. The REST tab is selected by default; provide the
value "Status" for the "Service name" field and press the "Create service" button.

![REST Services Screen](/asset/apigility-documentation/img/intro-first-rest-service-rest-services.png)
{'fraction_non_alphanumeric': 0.11512222853894258, 'fraction_numerical': 0.002558271745309835, 'mean_word_length': 3.5022392834293026, 'pattern_counts': {'":': 0, '<': 73, '<?xml version=': 0, '>': 77, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7191629', 'n_tokens_mistral': 2018, 'n_tokens_neox': 1939, 'n_words': 831}