# REST API

> Kullanıcı adı ve parolayla erişim anahtarı alın; cihaz, Edge Gateway ve alarm kuralı gibi Proxus nesnelerini OData ile okuyun veya değiştirin.

Kaynak: https://proxus.io/tr/docs/develop/rest-api

Bu kılavuzu tamamladığınızda betiğiniz merkez sunucuda oturum açar, bir erişim anahtarı alır ve cihazları bağlı
oldukları Edge Gateway'le birlikte okur. Aynı API ile nesne oluşturabilir, değiştirebilir ve silebilirsiniz. Bu
işlemlerin sınırını, oturum açan kullanıcının hakları belirler.

## Başlamadan önce

Şunlar gereklidir:

- Merkez sunucunun adresi. Yerel kurulumda bu adres örneğin `http://localhost:8080` olur. API, merkez sunucu
  ekranlarıyla aynı porttan çalışır.
- Entegrasyona ayrılmış bir Proxus kullanıcısı. API'nin neyi okuyup neyi değiştirebileceğini, ekranlarda olduğu gibi
  bu kullanıcının rolü belirler. Ayrıntılar için [Kullanıcılar ve roller](https://proxus.io/tr/docs/administer/users-and-roles)
  sayfasına bakın.
- İzleyeceğiniz örneğe göre `curl`, `requests` paketi kurulu Python 3 veya .NET.

## API uç noktaları

| Adres | İşlevi |
| --- | --- |
| `POST /api/Authentication/Authenticate` | Kullanıcı adını ve parolayı denetler, erişim anahtarı döndürür. |
| `/api/odata/<EntitySet>` | Nesneleri okur, oluşturur, değiştirir ve siler (OData v4). |
| `/api/odata/$metadata` | Veri modelinin tamamını verir: tüm varlık kümeleri, alanları ve bağlantıları. |
| `/swagger` | Tüm işlemleri listeleyen ve denemenizi sağlayan etkileşimli sayfa. |
| `POST /api/Telemetry/execute` | Saklanan veri noktası değerlerini döndürür. Ayrıntılar için [Telemetry API](https://proxus.io/tr/docs/develop/telemetry-api) sayfasına bakın. |

Varlık kümelerinden bazıları şunlardır: `Device`, `DeviceProfile`, `DeviceProfileRegister` (veri noktaları),
`Gateway`, `TargetProfile` (veri hedefleri), `NotificationChannel`, `Rule`, `RuleAction`, `Flow` (işlem akışları),
`Function`, `Alert`, `Log`, `ScheduledDelivery`, `TrendView` ve `UnsTopicPermission`. Listenin tamamı her zaman
`/api/odata/` adresinde bulunur.

## Adım 1: Erişim anahtarı alın

Kullanıcı adını ve parolayı JSON olarak gönderin. Yanıtta yalnızca erişim anahtarı düz metin olarak döner.

```bash
curl -X POST http://localhost:8080/api/Authentication/Authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName":"Admin","password":""}'
```

Sonraki tüm çağrılarda erişim anahtarını `Authorization` başlığına ekleyin:

```text
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

- Kullanıcı adı veya parola yanlışsa API `401` kodunu ve `User name or password is incorrect.` metnini döndürür.
- Geçerli bir erişim anahtarı içermeyen `/api/...` çağrıları `401`, kullanıcının yetkisi olmayan çağrılar `403`
  kodunu alır.
- Erişim anahtarı, `TokenExpireTime` ile belirlenen süre boyunca geçerlidir. Ürünle gelen yapılandırmada bu süre bir
  yıldır. Bir çağrı `401` döndürdüğünde yeni bir anahtar alın.

> **Uyarı:**
Merkez sunucu ilk açılışta kendine bir imzalama anahtarı üretir ve bu anahtarı paylaşılan yapılandırma klasöründe
(`Keys/UI/jwt-signing.key`) saklar. Tüm erişim anahtarları bu dosyayla imzalanır. Dosyayı ele geçiren biri geçerli
erişim anahtarı üretebilir, bu yüzden klasörü bir parola gibi koruyun. Erişim anahtarlarını başka bir sistem de
doğrulayacaksa `IssuerSigningKey` alanına kendi anahtarınızı girin. Diğer durumlarda bu alanı değiştirmeyin. Ayrıntılar için
[Yapılandırma anahtarları](https://proxus.io/tr/docs/reference/configuration#webapi) sayfasına bakın.

## Adım 2: Nesneleri okuyun

```bash
TOKEN=$(curl -s -X POST http://localhost:8080/api/Authentication/Authenticate \
  -H "Content-Type: application/json" -d '{"userName":"Admin","password":""}')

curl -s -G http://localhost:8080/api/odata/Device \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "\$filter=startswith(DeviceName,'LYS')" \
  --data-urlencode "\$select=Oid,DeviceName,Enabled" \
  --data-urlencode "\$count=true" \
  --data-urlencode "\$top=3"
```

Yanıt şöyle görünür:

```json
{
  "@odata.context": "http://localhost:8080/api/odata/$metadata#Device(Oid,DeviceName,Enabled)",
  "@odata.count": 14,
  "value": [
    { "Oid": 66, "DeviceName": "LYS_MILL_01", "Enabled": true },
    { "Oid": 67, "DeviceName": "LYS_LINE1_PLC", "Enabled": true },
    { "Oid": 69, "DeviceName": "LYS_PACKER_04", "Enabled": true }
  ]
}
```

Standart OData sorgu seçeneklerinin tümü kullanılabilir:

| Seçenek | Örnek | Not |
| --- | --- | --- |
| `$filter` | `Site eq 'Lyon Foods Plant'` | `eq`, `ne`, `gt`, `lt`, `and`, `or`, `startswith`, `contains` |
| `$select` | `Oid,DeviceName,Status` | Yalnızca belirtilen alanlar döner. |
| `$expand` | `Gateway($select=Name)` | Bağlantılı nesneyi de getirir. |
| `$orderby` | `DeviceName desc` | |
| `$top`, `$skip` | `$top=50&$skip=100` | `$top` en çok 100 olabilir. Daha büyük değerler `400` koduyla reddedilir. |
| `$count` | `$count=true` | Toplam sayıyı `@odata.count` alanında ekler. |

> **Uyarı:**
`$top` verilmezse sorgu, eşleşen tüm nesneleri tek yanıtta döndürür. `Log` veya `DeviceProfileRegister` gibi büyük
kümelerde `$top` ve `$skip` ile sayfa sayfa okuyun, `$select` listesini de kısa tutun.

Tek bir nesneyi okumak için anahtarını kullanın: `GET /api/odata/Device(69)`. `LatestValues` bağlantısını
genişletirseniz cihazın son değerleri de yanıta eklenir:

```bash
curl -s -G "http://localhost:8080/api/odata/Device(69)" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "\$select=DeviceName" --data-urlencode "\$expand=LatestValues"
```

Her son değer `Key`, `Value`, `DataType`, `Quality` ve `LastUpdate` alanlarını içerir.

## Adım 3: Koddan kullanın

```python
import requests

HUB = "http://localhost:8080"

# 1. Oturum açın ve erişim anahtarı alın
response = requests.post(
    f"{HUB}/api/Authentication/Authenticate",
    json={"userName": "Admin", "password": ""},
    timeout=30,
)
response.raise_for_status()
token = response.text.strip()
headers = {"Authorization": f"Bearer {token}"}

# 2. Bir tesisin cihazlarını Edge Gateway'leriyle birlikte okuyun
response = requests.get(
    f"{HUB}/api/odata/Device",
    params={
        "$filter": "Site eq 'Lyon Foods Plant'",
        "$select": "Oid,DeviceName,Status",
        "$expand": "Gateway($select=Name)",
        "$orderby": "DeviceName",
    },
    headers=headers,
    timeout=30,
)
response.raise_for_status()
for device in response.json()["value"]:
    print(device["Oid"], device["DeviceName"], device["Status"], device["Gateway"]["Name"])
```
```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var hub = new HttpClient { BaseAddress = new Uri("http://localhost:8080/") };

// 1. Oturum açın ve erişim anahtarı alın
var login = await hub.PostAsJsonAsync("api/Authentication/Authenticate",
    new { userName = "Admin", password = "" });
login.EnsureSuccessStatusCode();
var token = await login.Content.ReadAsStringAsync();
hub.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// 2. Edge Gateway'leri okuyun
using var gateways = JsonDocument.Parse(
    await hub.GetStringAsync("api/odata/Gateway?$select=Oid,Name"));
foreach (var gateway in gateways.RootElement.GetProperty("value").EnumerateArray())
    Console.WriteLine($"{gateway.GetProperty("Oid")} {gateway.GetProperty("Name")}");
```

## Oluşturma, değiştirme ve silme

Varlık kümeleri standart OData yöntemleriyle `POST` (oluşturma), `PATCH` (bazı alanları değiştirme), `PUT`
(nesnenin tamamını değiştirme) ve `DELETE` çağrılarını da kabul eder. Örneğin bir cihazı devre dışı bırakmak için:

```bash
curl -X PATCH "http://localhost:8080/api/odata/Device(69)" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"Enabled": false}'
```

Hangi işlemlere izin verildiğini kullanıcının rolü belirler. Rolün izin vermediği bir değişiklik, merkez sunucu
ekranlarında olduğu gibi API'de de reddedilir.

> **İpucu:**
`http://<hub>:8080/swagger` adresini açın, **Authorize** düğmesine tıklayın ve erişim anahtarını yapıştırın. Bu
sayfada her varlık kümesinin tüm işlemleri alanlarıyla birlikte listelenir. Çağrıları doğrudan tarayıcıdan
deneyebilirsiniz.

## Sonraki adımlar

- [Telemetry API](https://proxus.io/tr/docs/develop/telemetry-api): saklanan veri noktası değerlerini SQL ile sorgulayın.
- [MQTT ve UNS konuları](https://proxus.io/tr/docs/develop/mqtt): değerleri okundukları anda canlı alın.
- [Ağ portları ve uç noktalar](https://proxus.io/tr/docs/reference/ports): merkez sunucunun ve Edge Gateway'lerin dinlediği tüm adresler.