Added getting started and authentication page #224

MutiatBash · 2024-10-23T19:54:10Z

No description provided.

RCheesley

Thanks for the PR @MutiatBash - I've made a few comments but proper reviewing is blocked by #225 which is required to unblock building locally. I'm also noticing that Vale isn't checking this page correctly so we might need to check that, too.

RCheesley · 2024-10-24T07:39:23Z

docs/rest_api/getting_started.rst

+
+.. note:: 
+
+    Mautic has an API library available for PHP. You can `find it on GitHub <https://github.com/mautic/api-library>`_.


Suggested change

Mautic has an API library available for PHP. You can `find it on GitHub <https://github.com/mautic/api-library>`_.

Mautic has an API library available for PHP. Check out the :xref:`Mautic API Library`.

This needs converting to a link macro. There is already a link file in /links, you can check for the name and use the xref macro as above.

RCheesley · 2024-10-24T07:39:58Z

docs/rest_api/getting_started.rst

+
+To get started easily, you can use Mautic's Postman collection:
+
+.. image:: https://run.pstmn.io/button.svg


This is very incomplete right now, I'd personally leave this out until we fill it out a bit.

RCheesley · 2024-10-24T07:40:34Z

docs/rest_api/getting_started.rst

+       }
+   }
+
+.. vale off


Why are you turning off Vale here?

Hi @RCheesley ...Thank you very much fo your feedback...it's my first time writing rst or hearing about vale....I pretty much copied the content that was linked in the PR you dropped and just made little changes, so i'm really not sure why it was initially added...hence, the reason i didn't take it off...but i'll look into it.

RCheesley · 2024-10-24T07:41:50Z

docs/rest_api/getting_started.rst

+
+.. vale off
+
+API Rate limiter cache


Suggested change

API Rate limiter cache

API rate limiter cache

Looks like this one isn't yet resolved.

RCheesley · 2024-10-24T07:42:10Z

docs/rest_api/getting_started.rst

+
+``$version`` is in a semantic versioning format: ``[major].[minor].[patch]``. For example: ``2.4.0``. If you'll try it on the latest GitHub version, the version has ``-dev`` at the end. Like ``2.5.1-dev``.
+
+.. vale off


There is no need to turn Vale off here. Instead, fix the problem :)

RCheesley

@MutiatBash a small Vale fix here, too.

RCheesley · 2024-10-24T12:25:52Z

docs/rest_api/authentication.rst

+   * - Authorization code flow
+     - This flow is best if you want Users to log in with their own Mautic accounts. All actions taken get registered as if the User performed them in Mautic's UI.
+   * - Client Credentials flow
+     - This flow is best for Machine-to-Machine, M2M, communications. For example, in cron jobs that run on at fixed times of the day.


Suggested change

- This flow is best for Machine-to-Machine, M2M, communications. For example, in cron jobs that run on at fixed times of the day.

- This flow is best for Machine-to-Machine, M2M, communications. For example, in Cron jobs that run on at fixed times of the day.

Vale fix

MutiatBash · 2024-10-25T22:34:58Z

@RCheesley .....I've made the suggested changes, can you review them

RCheesley

Thanks for the great work @MutiatBash - just a few small tweaks to fix then it should be good to merge!

RCheesley · 2024-10-29T14:56:23Z

docs/rest_api/authentication.rst

+
+
+Plain HTTP requests
+===================


Suggested change

===================

===================

.. vale on

Turn it back on here.

RCheesley · 2024-10-29T14:57:04Z

docs/rest_api/authentication.rst

+   $api         = new MauticApi();
+   $contactsApi = $api->newApi('contacts', $auth, $apiUrl);
+   $contacts    = $contactsApi->getList();
+


Suggested change

.. vale off

Let's turn off Vale here as we are purposely going against the grammar rules to use a specific term.

RCheesley · 2024-10-29T14:58:34Z

docs/rest_api/authentication.rst

+   The OAuth processes can be tricky. If possible, it's best to use an OAuth library for the language that's used. If you're using PHP, Mautic recommends using the :xref:`Mautic API Library`.
+
+Step one - obtain authorization code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


These should be ~~~~ rather than ^^^^

RCheesley · 2024-10-29T14:58:44Z

docs/rest_api/authentication.rst

+You should compare the returned ``state`` against the original to ensure the request wasn't tampered with. 
+
+Step two - replace with an access token
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


RCheesley · 2024-10-29T14:58:51Z

docs/rest_api/authentication.rst

+Please store this data in a secure location and use it to authenticate API requests.
+
+Refreshing tokens
+^^^^^^^^^^^^^^^^^


RCheesley · 2024-10-29T15:00:07Z

docs/rest_api/authentication.rst

+
+.. warning:: 
+
+    Mautic's API library doesn't have support yet for this flow, but there's an open PR that adds support: https://github.com/mautic/api-library/pull/269


Please convert this to a link macro using the make link command, and commit the link file.

RCheesley · 2024-10-29T15:00:22Z

docs/rest_api/authentication.rst

+    Mautic's API library doesn't have support yet for this flow, but there's an open PR that adds support: https://github.com/mautic/api-library/pull/269
+
+
+Using plain OAuth2 for the Client Credentials flow


Wrap this in a vale off / vale on, also

RCheesley · 2024-10-29T15:00:33Z

docs/rest_api/authentication.rst

+    }
+
+
+Authenticating the API Request


Suggested change

Authenticating the API Request

Authenticating the API request

RCheesley · 2024-10-29T15:01:01Z

docs/rest_api/getting_started.rst

+       }
+   }
+
+Mautic version check


Wrap this one in a vale off / vale on.

RCheesley · 2024-10-29T15:01:33Z

docs/rest_api/getting_started.rst

+
+.. vale off
+
+API Rate limiter cache


Looks like this one isn't yet resolved.

RCheesley · 2024-11-12T13:07:58Z

Hi @MutiatBash give us a shout when you're ready for a re-review - it's helpful if you can mark the conversation resolved once you fix each item. Thanks!

MutiatBash added 2 commits October 23, 2024 19:30

Added getting started and authentication page

e161ab7

Updated Symfony Cache Link

c38b66b

MutiatBash mentioned this pull request Oct 23, 2024

Add getting started page to API documentation and add more to the Postman collection #217

Open

2 tasks

RCheesley requested changes Oct 24, 2024

View reviewed changes

RCheesley added 2 commits October 24, 2024 10:34

Merge branch '5.x' into rest-api-getting-started-page

dbb11a1

Merge branch '5.x' into rest-api-getting-started-page

af4c574

RCheesley requested changes Oct 24, 2024

View reviewed changes

RCheesley added documentation Improvements or additions to documentation pending-feedback labels Oct 24, 2024

updated getting started and authentication page

4e0def7

RCheesley requested changes Oct 29, 2024

View reviewed changes

Rest API : updated getting started and authentication page

08ce05a

RCheesley added the hacktoberfest-accepted label Oct 31, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added getting started and authentication page #224

Added getting started and authentication page #224

MutiatBash commented Oct 23, 2024

RCheesley left a comment

RCheesley Oct 24, 2024

RCheesley Oct 24, 2024

RCheesley Oct 24, 2024

MutiatBash Oct 25, 2024 •

edited

Loading

RCheesley Oct 24, 2024

RCheesley Oct 29, 2024

RCheesley Oct 24, 2024

RCheesley left a comment

RCheesley Oct 24, 2024

MutiatBash commented Oct 25, 2024

RCheesley left a comment

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley Oct 29, 2024

RCheesley commented Nov 12, 2024


		.. note::

		Mautic has an API library available for PHP. You can `find it on GitHub <https://github.com/mautic/api-library>`_.


		To get started easily, you can use Mautic's Postman collection:

		.. image:: https://run.pstmn.io/button.svg


		``$version`` is in a semantic versioning format: ``[major].[minor].[patch]``. For example: ``2.4.0``. If you'll try it on the latest GitHub version, the version has ``-dev`` at the end. Like ``2.5.1-dev``.

		.. vale off

	- This flow is best for Machine-to-Machine, M2M, communications. For example, in cron jobs that run on at fixed times of the day.
	- This flow is best for Machine-to-Machine, M2M, communications. For example, in Cron jobs that run on at fixed times of the day.


		.. warning::

		Mautic's API library doesn't have support yet for this flow, but there's an open PR that adds support: https://github.com/mautic/api-library/pull/269

		Mautic's API library doesn't have support yet for this flow, but there's an open PR that adds support: https://github.com/mautic/api-library/pull/269


		Using plain OAuth2 for the Client Credentials flow

	Authenticating the API Request
	Authenticating the API request

Added getting started and authentication page #224

Are you sure you want to change the base?

Added getting started and authentication page #224

Conversation

MutiatBash commented Oct 23, 2024

RCheesley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MutiatBash Oct 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RCheesley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MutiatBash commented Oct 25, 2024

RCheesley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RCheesley commented Nov 12, 2024

MutiatBash Oct 25, 2024 •

edited

Loading