Joomla Web Services API

<div class="title" style="font-size:150% !important">
  How to use<br>
  <span class="db8orange" style="font-size:170%">Web Services APIs</span><br>
  in and outside<br>your Joomla website?
</div>

<div class="title2">
<span class="apage1">by Peter Martin / <a href="https://db8.nl" target="_blank">db8.nl</a></span>
<br>
<span class="apage1">slides: <a href="https://petermartin.nl" target="_blank">https://petermartin.nl</a></span>

---

<div class="title">APIs and <span class="db8orange">Web Service APIs</span><br>
<ul style="font-size: 70%">
  <li>What's an API?</li>
  <li>API Tools</li>
  <li>Use external APIs in Joomla 5</li>
  <li>Use Joomla 5's API externally</li>
</ul>
</div>

---

----

#### <span class="db8orange">A</span>pplication <span class="db8orange">P</span>rogramming <span class="db8orange">I</span>nterface

Software interface to <span class="db8orange">communicate</span> with
<div class="grid" style="font-size:90%">
	<div class="blocks function fragment">
	"library-based" APIs<br>
    <span class="fragment">Software framework like Joomla<br>

```php
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

echo HtmlHelper::date(
  'now', 
  Text::_('DATE_FORMAT_LC6')
);
```
</span>
</div>
	<div class="blocks activate fragment">
    "network-based" APIs<br> 
    <span class="fragment">External websites<br>
    <ul>
          <li>Map (Google/OpenStreetmap)</li>
		  <li>Payment gateways</li>
          <li>CAPTCHA</li>
    </ul>
    </span>
	</div>
	<div class="blocks activate fragment">
      <a href="https://api.joomla.org/" target="_blank">https://api.joomla.org/</a>
	</div>
	<div class="blocks activate fragment">
    "network-based" API Protocols<br> 
    <span class="fragment">
    <ul>
		    <li>Simple Object Access Protocol (SOAP)</li>
            <li>Representational state transfer (REST)</li>
    </ul>
    </span>
	</div>
</div>

----

### REST<span style="text-transform:lowercase;">ful</span> API <span class="db8orange">Principles</span>

<div class="blocks function afragment">
    Uniform Interface<br>
    <span class="fragment">
    <ul>
          <li>Each resource ONE logical URI</li>
          <li>Same approach for ALL resources</li>
		  <li>Contain everything in its representation (+ HATEOAS links)</li>
    </ul>
  </span>
</div>

<div class="blocks activate afragment">
    Client-Server<br> 
    <span class="fragment">
    <ul>
          <li>NO dependency server <-> client</li>
          <li>Only dependency on the interface</li>
    </ul>
    </span>
</div>

<div class="blocks activate afragment">
      Stateless<br>
    <span class="fragment">
    <ul>
          <li>No client context stored on server</li>
          <li>Client responsible for state</li>
    </ul>
    </span>
</div>

<div class="blocks activate afragment">
    Cacheable<br> 
    <span class="fragment">
    <ul>
          <li>Performance for client</li>
          <li>Scalability server</li>
    </ul>
    </span>
</div>

<div class="blocks activate afragment">
    Layered System<br> 
    <span class="fragment">
    <ul>
          <li>Client agnostic to layers between client and actual server</li>
          <li>Cache = Layer</li>
    </ul>
    </span>
</div>

<div class="blocks activate afragment">
    Code on demand (optional)<br> 
    <span class="fragment">
    <ul>
          <li>Resource mostly XML or JSON</li>
          <li>Return of executable code allowed</li>
    </ul>
    </span>
</div>

</div>

<a href="https://restfulapi.net/rest-architectural-constraints" tartet="_blank">https://restfulapi.net/rest-architectural-constraints</a>

----

### REST <span class="db8orange">HTTP Methods</span>

<div class="blocks function afragment">
    POST<br>
    Create
</div>

<div class="blocks function afragment">
    PUT<br>
    Update
</div>

<div class="blocks function afragment">
    PATCH<br>
    Partial Modify
</div>

<div class="blocks function afragment">
    DELETE<br>
    Remove
</div>

</div>

---

<div class="title">API <span class="db8orange">Tools</span><br></div>

----

### <span class="db8orange">Browser</span>: Open Streetmap

db8 office: NYMA makersplaats<br>Winselingseweg 16, Nijmegen

<a href="https://www.openstreetmap.org/search?query=Winselingseweg+16%2C+Nijmegen#map=19/51.856553/5.838032" target="_blank">
https://www.openstreetmap.org/search?query=Winselingseweg+16%2C+Nijmegen</a>

----

### <span class="db8orange">Browser</span>: Open Streetmap <span class="db8orange">API</span>

My office: Winselingseweg 16, Nijmegen

<a href="https://nominatim.openstreetmap.org/search?q=Winselingseweg+16%2C+Nijmegen&format=jsonv2"
target="_blank">https://nominatim.openstreetmap.org/search?q=Winselingseweg+16%2C+Nijmegen&format=jsonv2</a>

```json
[{"place_id": 100724209, 
  "licence": "Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
    "osm_type": "node", "osm_id": 9423420888,
    "lat": "51.8565531", "lon": "5.8380321",
    "category": "place", "type": "house",
    "place_rank": 30, "importance": 0.000068507667658457,
    "addresstype": "place", "name": "",
    "display_name": "16, Winselingseweg, Batavia, Haven- en industrieterrein, Nijmegen-Nieuw-West, Nijmegen, Gelderland, Netherlands, 6541 AK, Netherlands",
    "boundingbox": ["51.8565031","51.8566031","5.8379821","5.8380821"]
}]
```

----

### <span class="db8orange">CLI</span> API tool: <span class="db8orange">CURL</span>

```bash
$ curl "https://nominatim.openstreetmap.org/search?q=Winselingseweg+16%2C+Nijmegen&format=jsonv2"
```

```json
[{"place_id":99579905,"licence":"Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright",
  "osm_type":"node","osm_id":9423420888,
  "lat":"51.8565531","lon":"5.8380321",
  "category":"place","type":"house",
  "place_rank":30,"importance":6.850766765845759e-05,
  "addresstype":"place","name":"",
  "display_name":"16, Winselingseweg, Batavia, Haven- en industrieterrein, Nijmegen-Nieuw-West, Nijmegen, Gelderland, Nederland, 6541 AK, Nederland",
  "boundingbox":["51.8565031","51.8566031","5.8379821","5.8380821"]}] 
```

``` curl `something` | json_pp```

</span>

----

### <span class="db8orange">IDE</span> API tool: <span class="db8orange">Plugin</span>

- <span class="db8orange">PHPStorm</span> > HTTP Client plugin
  - create, edit, execute HTTP requests<br>in PhpStorm code editor
- <span class="fragment"><span class="db8orange">Visual Studio Code</span> > NO HTTP Client plugin
    - available through extensions</span>

----

### <span class="db8orange">Software</span>: <span class="db8orange">Postman API Platform</span>

- Download: <a href="https://www.postman.com/downloads/" target="_blank">https://www.postman.com/downloads/</a>

----

### <span class="db8orange">Software</span>: <span class="db8orange">Bruno</span>
Fast, Git-Friendly Open Source API Client

- Download: <a href="https://www.usebruno.com/" target="_blank">https://www.usebruno.com/</a>
- Supports importing Postman Collections!

---

<div class="title">Use <span class="db8orange">external Web Services APIs</span><br>in your Joomla 5</div>

----

### Examples of <span class="db8orange">external APIs</span>

- External <span class="db8orange">data</span> available
  - CAPTCHA anti-spam
  - Latitude / Longitude
  - Weather
- External <span class="db8orange">functionality</span>
  - Processing a Payment & returning status

----

### <span class="db8orange">CAPTCHA</span> anti-spam

- CAPTCHA - reCAPTCHA (Google)
- CAPTCHA - Invisible reCAPTCHA (Google)
- CAPTCHA - hCaptcha (<a href="https://data2site.com/extensions/hcaptcha" target="_blank">data2site.com</a>)

----

### <span class="db8orange">Latitude/Longitude</span> Custom Field

<span style="float:left;width:700px;">
<ul>
  <li><span class="db8orange">YOOtheme Pro</span>: Upon save<ul>
    <li>looks up latitude/longitude via API</li>
    <li>stores lat/long in a Custom Field</li>
    <li>Map view uses lat/long</li>
    </ul>
  </li>
  <li class="fragment"><span class="db8orange">Radius search</span>? custom plugin<ul>
    <li>triggered upon save</li>
    <li>store lat/long in separate table</li>
    <li>filter articles bases on location (lat/long)</li>
    </ul>
  </li>
</ul>
</span>

----

### <span class="db8orange">Weather</span> in module

- URL Builder at <a href="https://open-meteo.com/en/docs#api_form" target="_blank">https://open-meteo.com/en/docs#api_form</a>

```json
"lat":"51.8565531", "lon":"5.8380321",
```

- URL: <a href="https://api.open-meteo.com/v1/forecast?latitude=51.8565531&longitude=5.8380321&hourly=temperature_2m" target="_blank">https://api.open-meteo.com/v1/forecast?latitude=51.8565531&longitude=5.8380321&hourly=temperature_2m</a>

----

### Custom <span class="db8orange">Weather Module</span>

```php
$url     = 'https://api.open-meteo.com/v1/forecast
?latitude=51.8565531&longitude=5.8380321&hourly=temperature_2m';
$fetched = file_get_contents($url);
$content = json_decode($fetched, true);

if (!$content)
{
	print("No data found");
}

print_r($content);
```

----

#### Google Spreadsheet

- Credentials
- Settings
- Language versions

---

<div class="title">Use Joomla 5's<br><span class="db8orange">Web Services API externally</span></div>

----

#### Joomla 5's <span class="db8orange">Web Services API externally</span>

<ul>
<li>API access - limited to Super User accounts?<ul>
<li class="fragment"><span class="db8orange">TIP</span>: Create Super User account,<br>change it to lower level,<br>set Permissions</li></ul>
</li>
<li class="fragment">No HATEOS - no links to other end-points</li>
<li class="fragment">Moving site? regenerate API Token!</li>
</ul>

----

### Joomla <span class="db8orange">API token</span>

Users > Manage > edit "account" > [Joomla API Token]

----

### Joomla <span class="db8orange">API endpoints</span>

<div class="blocks function afragment">
    Documentation:<br>
<a style="font-size:70%" href="https://docs.joomla.org/J4.x:Joomla_Core_APIs" target="_blank">
  https://docs.joomla.org/J4.x:Joomla_Core_APIs</a>
<a style="font-size:70%" href="https://manual.joomla.org/docs/general-concepts/webservices/" target="_blank">
  https://manual.joomla.org/docs/general-concepts/webservices/</a>
</div>

<div class="blocks function fragment">
    Get List of Articles<br>
    curl -X GET /api/index.php/v1/content/articles
</div>

<div class="blocks function fragment">
    Get Single Article<br>
    curl -X GET /api/index.php/v1/content/articles/{article_id}
</div>

<div class="blocks function fragment">
    Delete Article<br>
    curl -X DELETE /api/index.php/v1/content/articles/{article_id}
</div>

<div class="blocks function fragment">
    Create Article<br>
    curl -X POST -H "Content-Type: application/json" /api/index.php/v1/content/articles -d<br>

```json
{
    "alias": "my-article",
    "articletext": "My text",
    "catid": 64,
    "language": "*",
    "metadesc": "",
    "metakey": "",
    "title": "Here's an article"
}
```

</div>

<div class="blocks function fragment">
    Update Article<br>
    curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/articles/{article_id} -d<br>

```json
{
    "id": 64,
    "title": "Updated article"
}
```

</div>
</div>

----

### Get List of Articles

```bash
$ curl https://example.com/api/index.php/v1/content/articles 
-H "Authorization: Bearer 
c2hhMjU2OjgxNjo2NTg1YWIwMTY0XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```

----

### Get Single Article via ID

```bash
$ curl https://exmp.com/api/index.php/v1/content/articles/11 
-H "Authorization: Bearer 
c2hhMjU2OjgxNjo2NTg1YWIwMTY0XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
| json_pp
```

----

### Expose <span class="db8orange">own component</span> endpoint

<br>

- via Plugin
  - plg_webservices_yourcomponent

<br>
<br>
<a style="font-size:80%" href="https://docs.joomla.org/J4.x:Adding_an_API_to_a_Joomla_Component" target="_blank">
https://docs.joomla.org/J4.x:Adding_an_API_to_a_Joomla_Component</a>

---

<div class="title"><span class="db8orange">Postman</span><br></div>

----

### <span class="db8orange">Postman</span>

----

### API <span class="db8orange">End points</span> in Postman?

<ul class="fragment">
  <li>Alexandre Elisé (Martinique, France)<ul>
    <li><a style="font-size:80%" href="https://github.com/alexandreelise/j4x-api-collection" target="_blank">https://github.com/alexandreelise/j4x-api-collection</a></li>
    </ul>
  </li>
</ul>

----

### <span class="db8orange">Run</span> J4 API Collection in <span class="db8orange">Postman</span>

- <a style="font-size:80%" href="https://github.com/alexandreelise/j4x-api-collection" target="_blank">https://github.com/alexandreelise/j4x-api-collection</a>

----

### <span class="db8orange">Config</span> J4 API Collection in <span class="db8orange">Postman</span>

- edit > Variables
  - base_url = http://example.com<br>(NO trailing slash in URL!)
  - base_path = api/index.php/v1
  - auth_apikey = c2hhMjU2OjgxNTo3XXXXXXXXXXXXXXXXXXXXXXXX

----

### Bruno

Download Bruno: <a href="https://www.usebruno.com/" target="_blank">https://www.usebruno.com/</a>

And import the Joomla Postman API collection in Bruno...

---

<div class="title">check check <span class="db8orange">double check</span></div>

----

### <span class="db8orange">Save</span> time!

<ul>
  <li>Docker? check <span class="db8orange">ports</span></li>
  <li class="fragment">Postman: check URL, <span class="db8orange">no trailing slash</span>!</li>
  <li class="fragment">Test API with: <span class="db8orange">curl</span></li>
  <li class="fragment">Test <span class="db8orange">php</span>: <span style="font-family: monospace; font-size: 70%">print_r(curl_error($curl));</span></li>
  <li class="fragment">Connection errors? - test at <span class="db8orange">other server</span></li>
  <li class="fragment">Move website - <span class="db8orange">regenerate</span> API Token !</li>
</ul>

---

<div class="title">Demo:<br><span class="db8orange">Using Web Services API</span><br></div>

----

#### Create new Group + User

<ul>
  <li><span class="db8orange">With Super User "admin"</span>:
    <ul>
      <li>Create new User Group "API users"</li>
      <li>Create new User "API user"</li>
      <li>Assign to group "Super Users"</li>
    </ul>
  </li>
  <li class="fragment"><span class="db8orange">Log in as "API user"</span>, generate API Token, log out</li>
  <li class="fragment"><span class="db8orange">With Super User "admin"</span>:
    <ul>
      <li>Change for "API user":</li>
      <ul>
        <li>Remove from Group "Super Users"</li>
        <li>Add to User Group "API users"</li>
      </ul>
    </ul>
  </li>
</ul>

----

#### Get all articles

```bash
curl https://initech.db8.nl/api/index.php/v1/content/articles \
-H "Authorization: \
Bearer c2hhMjU2OjgxNTozMDg2YTYyOWU3YmJmNzA4NTU4MTA0YjA0ZmIxNTRlNTkzNDUwNjM0ZGY2NDA5ZjgzNTRkZDkyYzJlZmQ2NGUz"
```

```txt
{"errors":[{"title":"Forbidden"}]}
```
</span>

<span class="fragment">
Give User Group "API users" access:
</span>
<br>
<span class="fragment">
Global Configuration > Permissions > User Group "API users" > 
<span class="db8orange">Web Services Login</span>: "Allowed"
</span>

----

#### Get only articles from category Team 
https://initech.db8.nl/administrator/index.php?option=com_content&view=articles&filter[category_id][]=13<br>
<br>?filter[catid]=13 = ?filter%5Bcatid%5D=13

```bash
curl -X GET "https://initech.db8.nl/api/index.php/v1/content/articles?filter%5Bcatid%5D=13" \
  -H "Authorization: Bearer c2hhMjU2OjgxNTozMDg2YTYyOWU3YmJmNzA4NTU4MTA0YjA0ZmIxNTRlNTkzNDUwNjM0ZGY2NDA5ZjgzNTRkZDkyYzJlZmQ2NGUz"
```

----

#### Get only 1 article from category Team

?filter%5Bcatid%5D=13<span class="db8orange">&list%5Blimit%5D=1</span>

```bash
curl -X GET "https://initech.db8.nl/api/index.php/v1/content/articles?filter%5Bcatid%5D=13&list%5Blimit%5D=1" \
  -H "Authorization: Bearer c2hhMjU2OjgxNTozMDg2YTYyOWU3YmJmNzA4NTU4MTA0YjA0ZmIxNTRlNTkzNDUwNjM0ZGY2NDA5ZjgzNTRkZDkyYzJlZmQ2NGUz"
```

----

#### Create new article in category News

```bash
curl -X POST "https://initech.db8.nl/api/index.php/v1/content/articles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer c2hhMjU2OjgxNTozMDg2YTYyOWU3YmJmNzA4NTU4MTA0YjA0ZmIxNTRlNTkzNDUwNjM0ZGY2NDA5ZjgzNTRkZDkyYzJlZmQ2NGUz" \
  -d '{
    "alias": "joomladagen-2025",
    "articletext": "Morgen geef ik een presentatie over <strong>Joomla Framework</strong>. Daar laat ik een andere manier zien hoe je <strong>zonder Joomla</strong> en met enkele Joomla libraries kunt gebruiken om <strong>data uit een Joomla database</strong> te halen, zonder de Web Services API",
    "catid": 14,
    "language": "*",
    "metadesc": "",
    "metakey": "",
    "title": "Joomladagen 2025",
    "state": 1
  }'
````

```txt
{"errors":[{"title":"Forbidden"}]}
```
</span>

----

#### Create new article in category News

<span class="fragment">
Global Configuration > Permissions > User Group "API users" > <br>
<span class="db8orange">Create</span>: "Allowed"
</span>
<br><br>
<span class="fragment">
Unpublished?
</span>
<br><br>
<span class="fragment">
<span class="db8orange">Change State</span>: "Allowed"
</span>

---

<div class="title"><span class="db8orange">Questions</span>?</div>

----

## Photo Credits

<ul style="font-size:50%">
  <li>https://www.pexels.com/photo/close-up-photo-of-toy-bot-8566472/</li>
  <li>https://pixabay.com/photos/notebook-paper-pages-open-731212/</li>
  <li>https://www.pexels.com/photo/high-angle-photo-of-robot-2599244/</li>
  <li>https://unsplash.com/photos/iuuJC_pjLU0</li>
  <li>https://www.pexels.com/photo/man-in-red-polo-shirt-sitting-near-chalkboard-3779448/</li>
  <li>https://www.pexels.com/photo/cheerful-young-woman-screaming-into-megaphone-3761509/</li>
  <li>https://unsplash.com/photos/fVzrhGkLLaY</li>
  <li>https://www.pexels.com/photo/a-man-and-a-woman-wearing-white-coats-and-protective-goggles-8439008/</li>
  <li>https://unsplash.com/photos/a-group-of-white-and-orange-objects-IVGZ6NsmyBI</li>
</ul>

</section>