# Adding an API function

***

In this contribute section, it will be explain how to add a function to the API.

If you don't know how to make a pull request (Demand to change the code), you may see this [explaination](/docs/informations/contribute.md#how-to-make-a-pull-request).

{% stepper %}
{% step %}
**Research**

Before you code a new function for Dispy, you need to know exactly how to do it.

In the [documentation](https://discord.com/developers/docs/intro) of discord, you can find every possible API requests, e.g. [Request to create a message](https://discord.com/developers/docs/resources/message#create-message). You will need theses informations to continue.
{% endstep %}

{% step %}
**Amount**

In Dispy, your function can be in multiple place, e.g. to create a message:

* bot.create\_message() which need all arguments
* message.reply() which need content and a message object
* channel.send() which need content and a channel object

An API function need to be present on types that has the necessary informations and on the bot object.
{% endstep %}

{% step %}
**Where**

The API function for the bot object are located in **dispy.modules.*****rest\_api.py***.

For an object (e.g. Message), they are located in **dispy.types** and the file which contain the definition of the object. If the object doesn't exist, follow this guide[^1].
{% endstep %}

{% step %}
**Introduction**

If the object doesn't have the `_api = None` argument, you need to add it at the end of all the type definition. With this you can call the \_\_request\_\_ object.

You need to import these two thing (if they are not already imported):

```python
from dispy.modules.result import result
import asyncio
```

{% endstep %}

{% step %}
**Create the Function**

When creating a function, you need to follow some rules to be sure your pull request will be accepted.

* If the API request return something, it need to has a type object (If it doesn't exist, create it using this guide[^1]) or put 'None' if nothing is returned
* It need to be asynchronous.
* It need to be using the internal function of Dispy (`result` & `__request__`)
* The line using \_\_request\_\_ need to have the comment `# no_traceback` at the end.
* Your function need to have a description.
* Your function need to return a result object and it need to be set when the request send a response. Use the damn template x).

Template:

```python
def function(self, argument=None, **kwargs) -> result[<Type>]:
    """
    Description
    """
    future = self._api._loop.create_future()
    
    async def _asynchronous():
        payload = {}
        
        # Your code here!
        
        result = await self._api.__request__('<method>', f'<path>', payload) # no_traceback
        future.set_result(result)
    
    asyncio.run_coroutine_threadsafe(_asynchronous(), self._api._loop)
    return result[<Type>](future,self._api,<Type>)
```

**What's to change in the template**

1. There is 3 `<Type>` to replace with the return type object, you can put 'None'.
2. You need to change `<method>` to the method used in the API request, e.g. Post, patch, delete.
3. And `<path>`, you replace by the API path given by the Discord documentation.

{% hint style="danger" %}
Some arguments will need to be passed through **run\_coroutine\_threadsafe**.
{% endhint %}
{% endstep %}

{% step %}
Testing

It is important to test your functions before doing a pull request. Please.
{% endstep %}
{% endstepper %}

And you're done! Time to open a pull request

[^1]: There is no guide yet.

    Ask the developer :)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dispy.gitbook.io/docs/informations/contribute/adding-an-api-function.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.