py-rest-client 0.1.1

Py-Rest-Client is a useful lib for programmers who work with clients for REST API. In simply and easy way you can build Endpoint classes where you put endpoint settings.In that case you have clean structure of endpoints in your code. This lib is only for consume REST API endpoints.

# Endpoint
This is the main thing what you will use in that lib.With this class you can easy create clean structure of you rest api clients.

We recommend create separate file for it i.e. endpoints.py

To use it you have to put that class as parent in your Endpoint Class.

### Mandatory objects:

- `endpoint`: the path to your endpoint i.e. `/user/{user_id}/details/`. To use endpoint parameters put them into curly braces: `{endpoint_parameter}` in your endpoint's path.
- method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE` method. You can set it as `Request.GET` or as a string `get`.

### Optional objects:

- `header` (`dict`) - set it if you need to send request to endpoints with some headers values.
- `cookies` (`dict`) - set it when you need include cookies inside your request.
- `auth` (`tuple`) - set it when you need authorization in your requests. This field should be set as instance of auth class. Check auth.py file.
- `payload` (`dict`) - set it when you need to send `GET` or `POST` or `PATCH` or `PUT` or `DELETE` with parameters. You can set it directly as field in Endpoint class or as argument when you create Endpoint's instance.

### Instance fields:
- `payload` (`dict`) - definition above.
- `url_params` (`dict`) - you set this when you use parameters in your endpoint path.

Lets do some example code!

### HOW TO INSTALL

`pip install py-rest-client`

### HOW TO SET SETTINGS

Before you start using `rest-client` lib you have to set correctly your settings variables.

On the first step you have to put correct `REST_CLIENT_SETTINGS_MODULE` in you `__init__.py`.

```python
# __init__.py in main dir where you have project.
import os

os.environ.setdefault("REST_CLIENT_SETTINGS_MODULE", "your_project_name.settings") # this is only example
```

Now you can creaet `settings.py` file and set those variables:

```python
# Those are only examples of values.
REST_SERVER_HOST = '0.0.0.0'
REST_SERVER_PROTOCOL = 'http://'
REST_SERVER_PORT = '8000'
```

Don't worry if you didn't set correct path to `settings module` or `settings variables` in `settings.py`.

You will be informed about that.

```python
# when you set bad path to settings module
ImportError: No module named 'my_path_to_settings'
```

```python
# when you didn't set correctly one of variables.
AttributeError: module 'rest_client.your_project.settings' has no attribute 'REST_SERVER_PROTOCOL'
```


### Lesson 1

In first lesson we show you how we handle errors in our `rest-client`. We create endpoint with wrong endpoint url.

```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram_404'

istagram = InstagramEndpointGET()
# raises exception:
# rest_client.exceptions.EndpointError: 404 Not Found
```

It handles all REST API errors.

### Lesson 2

In this lesson we show you how to create simple endpoint which use method `GET` and `endpoint` path to fetch data from REST API.

#### Mock response:
```json
{
"data": [
{
"type": "image",
"users_in_photo": [],
"filter": "Earlybird",
"tags": ["expobar"],
"comments": {
"count": 0
}
}
]
}
```

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram'


instagram = InstagramEndpointGET()

print(instagram.objects.values())
# returns:
# {'data': [{'filter': 'Earlybird', 'comments': {'count': 0}, 'type': 'image', 'users_in_photo': [], 'tags': ['expobar']}]}

print(instagram.objects.data) # you can use dot notation to get values from fields.
# returns:
# InstagramEndpointGET.data: [TestInstagramEndpointGET.data[0]: {'users_in_photo': [], 'filter': 'Earlybird', 'type': 'image', 'tags': ['expobar'], 'comments': {'count': 0}}]

print(instagram.objects.data[0].type) # you can use dot notation and indexes to get value from fields.
# returns:
# InstagramEndpointGET.data[0].type: image

for field, value in testing.objects.data[0].values().items():
print("{field}: {value}".format(field=field, value=value))

# returns:
# type: image
# tags: ['expobar']
# comments: {'count': 0}
# filter: Earlybird
# users_in_photo: []
```

In this snippet we've created Endpoint's Class with method `GET` and enpoint's path `api/v1/instagram`.

The response is in `json` format as we have in all Rest APIs.

To fetch data from this endpoint you have to create instance of your endpoint - in this moment you call endpoint with `GET` request. Fetched data is stored in field `objects`.

To see what the endpoint returned you can use `values()` method by calling it directly on `objects` field. This method returns data as python objects.

```python
endpoint_instance.objects.values()
```

To get values from `objects` use dot notation to call them. It returns python types: `int`, `float`,`string`, `list` and `dict`. You can use them as standard python fields.

```python
endpoint_instance.objects.data
```

When endpoint returns `list` you can use dot notation with indexes.

```python
endpoint_instance.objects.list_data[0].some_field
```

** In the same way you can use endpoitn with methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. All REST API responses are handle in the same way. You can use `values()` method and dot notation. Response is always stored in `objects` field.

### Lesson 3

In this lesson we show you how to create simple endpoint which uses method `GET` and `endpoint` path to fetch data from REST API with `url_param`.

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram/user/{user_id}'

instangram = InstagramEndpointGET(url_param={'user_id': 1})
instagram.values()
```

### Lesson 5

We know that sometimes we need to send `payload` or `body` in your request. In that case you have to create `endpoint` instance with `payload` as `argument`.

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram/user/{user_id}'

instangram = InstagramEndpointGET(url_param={'user_id': 1}, payload={'country': 'UK'})
instagram.values()
```

### Lesson 6

Now it's time to show you how to create Endpoint when you need to send request with authentication.

We handle 3 types of authentication:
- `HTTPBasicAuth('user', 'password')`
- `HTTPDigestAuth('user', 'password')`
- `OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET', 'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')`

You need to choose one from above and put it as a `field` in `Endpoint` class.

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram/user/{user_id}'
auth = HTTPBasicAuth('user', 'password')

instangram = InstagramEndpointGET(url_param={'user_id': 1})
instagram.values()
```

### Lesson 7

You should read that lesson if you would like to handle `endpoint` with `cookies`. You have to put `cookies` as a field in `Endpoint` class.

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram/user/{user_id}'
cookies = {'some_cookie`: 'some_cookie_value'}

instangram = InstagramEndpointGET(url_param={'user_id': 1})
instagram.values()
```

### Lesson 8

Sometimes we have to send request with `headers`. To implement it you need set it as a `Enpoint` class `field`.

#### Rest-Client
```python
class InstagramEndpointGET(Endpoint):
method = Request.GET
endpoint = 'api/v1/instagram/user/{user_id}'
headers = {'some_headers`: 'some_header_value'}

instangram = InstagramEndpointGET(url_param={'user_id': 1})
instagram.values()
```