# Crate aws-arn
Provides the types, builders, and other helpers to manipulate AWS
[Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)
strings.
[](https://crates.io/crates/aws-arn)
[](https://docs.rs/aws-arn)
[](https://github.com/johnstonskj/rust-aws-arn/stargazers)
The ARN is a key component of all AWS service APIs and yet nearly all client
toolkits treat it simply as a string. While this may be a reasonable and
expedient decision, it seems there might be a need to not only ensure
correctness of ARNs with validators but also constructors that allow making
these strings correclt in the first place.
# ARN Types
This crate provides a number of levels of ARN manipulation, the first is the
direct construction of an ARN type using the core `ResourceName`,
`Identifier`, `AccountIdentifier`, and `ResourceIdentifier` types.
```rust
use aws_arn::{ResourceName, ResourceIdentifier};
use aws_arn::known::{Partition, Service};
use std::str::FromStr;
let arn = ResourceName {
partition: Some(Partition::default().into()),
service: Service::S3.into(),
region: None,
account_id: None,
resource: ResourceIdentifier::from_str("mythings/thing-1").unwrap()
};
```
In the example above, as we are defining a minimal ResourceName we could use one of the
defined constructor functions.
```rust
use aws_arn::{ResourceName, ResourceIdentifier};
use aws_arn::known::Service;
use std::str::FromStr;
let arn = ResourceName::aws(
Service::S3.into(),
ResourceIdentifier::from_str("mythings/thing-1").unwrap()
);
```
Alternatively, using `FromStr,` you can parse an existing ARN string into an ARN value.
```rust
use aws_arn::ResourceName;
use std::str::FromStr;
let arn: ResourceName = "arn:aws:s3:::mythings/thing-1"
.parse()
.expect("didn't look like an ResourceName");
```
Another approach is to use a more readable *builder* which also allows you to ignore those fields
in the ARN you don't always need and uses a more fluent style of ARN construction.
```rust
45Muse aws_arn::builder::{ArnBuilder, ResourceBuilder};
use aws_arn::known::{Partition, Service};
use aws_arn::{ResourceName, Identifier};
use std::str::FromStr;
let arn: ResourceName = ArnBuilder::service_id(Service::S3.into())
.resource(ResourceBuilder::named(Identifier::from_str("mythings").unwrap())
.resource_name(Identifier::new_unchecked("my-layer"))
.build_resource_path())
.in_partition_id(Partition::Aws.into())
.into();
```
Finally, it is possible to use resource-type specific functions that allow an even more direct and
simple construction (module `aws_arn::builder::{service}` - *service builder functions*, although
at this time there are few supported services.
```rust
use aws_arn::builder::s3;
use aws_arn::Identifier;
use std::str::FromStr;
let arn = s3::object(
Identifier::from_str("mythings").unwrap(),
Identifier::from_str("thing-1").unwrap(),
);
```
For more, see the AWS documentation for [Amazon Resource Name
(ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) documentation.
# Optional Features
This crate has attempted to be as lean as possible, with a really minimal set of dependencies,
we have include the following capabilities as optional features.
* `builders` adds the builder module. This feature is enabled by default, it also requires the
`known` feature.
* `known` adds a module containing enums for partitions, regions, and services.
This feature is enabled by default.
* `serde_support` adds derived `Serialize` and `Deserialize` implementations for the `ARN` and
`Resource` types. This feature is enabled by default.
## Changes
**Version 0.3.0**
* **Breaking Change**: Renamed `ARN` to `ResourceName`.
* **Breaking Change**: Renamed `ArnError` to `Error`.
* Added interface for common Identifier operations.
* Added variable expansion for `ResourceIdentifier` and `ResourceName`.
* Added more unit tests.
**Version 0.2.1**
* Created a new `AccountIdentifier` type for the 12-digit value.
* `consts` feature renamed `known`.
**Version 0.2.0**
* Relaxed validation of identifiers and resource identifiers.
* Removed `Resource` type which added a lot of the validation confusion.
* Using new `Identifier` and `ResourceIdentifier` types to construct correct `ARN` values without the need for any
external validation methods.
* Replaced `ResourceBuilder` with one for `ResourceIdentifier` values.
* Removed `ext_validation` feature
* Added `consts` feature
* Placed `builder` module into new `builders` feature.
* Added a lot more tests including an `examples.txt` file that is just a long list to be parsed.
* Fixed Github [issue-2](https://github.com/johnstonskj/rust-aws-arn/issues/2).
**Version 0.1.1**
* Documentation additions and fixes, in both README and Rustdoc.
* Renamed service builder functions, added a parent/child pattern for s3.
* Added Serde feature.
* Made external validation optional.
**Version 0.1.0**
* Initial commit.
* Provides basic ARN type with `Display` and `FromStr`.
* Provides scaffolding for service-specific validation.
* Provides initial set of service builder, `make_{format}`, functions for ARN construction.
## TODO
* More tests!
* More service formats for validation.
* More service builder functions.